> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-platform/6/monitor/log/troubleshoot/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Troubleshoot logging

> Diagnose and resolve common logging problems

Diagnose and resolve common logging problems in Itential Platform.

## Before you begin

* Administrator access to Itential Platform
* Your Platform version (check **Admin Essentials → About**)
* Familiarity with [log severity levels](./log-levels-reference)

## Collect logs for support

Choose the appropriate collection method based on whether you need JSON formatting preserved.

| Method                 | Preserves JSON | Captures all output | Single file | Best for               |
| ---------------------- | -------------- | ------------------- | ----------- | ---------------------- |
| journalctl             | No             | Yes                 | Yes         | Quick support requests |
| Direct file collection | Yes            | No                  | No          | JSON parsing, analysis |

### Collect using journalctl

First, identify your service name:

| Platform version   | Service name        |
| ------------------ | ------------------- |
| 6.2 and later      | `itential-platform` |
| 6.1                | `itential`          |
| 2023.2 and earlier | `pronghorn`         |

Check the running service:

```bash
systemctl status itential-platform
```

Collect all logs:

```bash
journalctl -u itential-platform > itential-logs-$(date +%Y%m%d).log
```

Collect from a time range:

```bash
# Last hour
journalctl -u itential-platform --since "1 hour ago" > logs.txt
 
# Specific range
journalctl -u itential-platform --since "2024-11-20 10:00:00" --until "2024-11-20 15:00:00" > logs.txt
```

### Collect log files directly

Collect files directly from the filesystem to preserve JSON formatting:

```bash
# Platform 6
tar -czf itential-logs-$(date +%Y%m%d).tar.gz /var/log/itential/
 
# Platform 2023.2 and earlier
tar -czf pronghorn-logs-$(date +%Y%m%d).tar.gz /var/log/pronghorn/
```

Before sharing logs with third parties, review them for sensitive data from third-party systems. Itential Platform excludes AAA sensitive data but does not modify third-party payloads.

## Missing log messages

If expected log messages don't appear, verify your logging configuration and directory permissions.

### Check the log level

Each log level excludes lower-severity messages. Setting `log_level` to `info` excludes `debug` messages.

**Platform 6:** Navigate to **Admin Essentials → Configuration → Logging** and check `log_level`.

**Platform 2023.2 and earlier:** Navigate to **Admin Essentials → Profiles → \[your profile] → Configure → loggerProps** and check `log_level`.

### Enable verbose logging temporarily

#### Increase log verbosity

Set `log_level` to `debug`, save, and restart Platform.

#### Reproduce the issue

Capture the relevant log output.

#### Restore normal verbosity

Return `log_level` to `info` or `warn` and restart Platform.

### Enable debug for a specific adapter

To minimize performance impact, enable debug logging on individual adapters rather than globally:

#### Open the adapter

Navigate to **Admin Essentials → Adapters** and select the adapter.

#### Set log level

Click the **Logging** tab. Set **File Log level** to `debug`.

#### Save and restart

Save and restart the adapter.

### Check component overrides

Individual components may override global logging settings.

#### Open the component

Navigate to **Admin Essentials → Applications**, **Adapters**, or **Integrations** and select the component.

#### Verify the log level

Click the **Logging** tab and check the log level. Reset to global settings if needed.

#### Restart if needed

Restart adapters to apply changes. Application changes apply immediately.

### Verify the log directory

Ensure the log directory exists with proper permissions.

Check the directory:

```bash
# Platform 6
ls -ld /var/log/itential
 
# Platform 2023.2 and earlier
ls -ld /var/log/pronghorn
```

The directory should be owned by `itential` with `755` permissions. If it is missing, create it:

```bash
# Platform 6
sudo mkdir -p /var/log/itential
sudo chown itential:itential /var/log/itential
sudo chmod 755 /var/log/itential
 
# Platform 2023.2 and earlier
sudo mkdir -p /var/log/pronghorn
sudo chown itential:itential /var/log/pronghorn
sudo chmod 755 /var/log/pronghorn
```

Restart Platform after creating the directory.

### Check the system journal

Check the system journal for logging initialization errors or permission issues:

```bash
journalctl -u itential-platform --since "10 minutes ago"
```

Look for permission problems, configuration errors, or disk space constraints.

## Logs missing from a specific time period

If logs from a specific time period are missing, rotation may have deleted them before you could retrieve them.

### Check rotation settings

**Platform 6:** **Admin Essentials → Configuration → Logging** — check `log_max_file_size` and `log_max_files`.

**Platform 2023.2 and earlier:** **Admin Essentials → Profiles → \[your profile] → Configure → loggerProps** — check `log_max_file_size` and `log_max_files`.

### Calculate retention period

Use this formula to estimate how many days of logs your current settings retain:

```
Days of retention = (log_max_file_size × log_max_files) / estimated daily log volume
```

**Example:**

* `log_max_file_size`: 10485760 (10 MB)
* `log_max_files`: 10
* Estimated daily log volume: 50 MB
* Retention = (10 MB × 10) / 50 MB per day = **two days**

### Increase retention

Adjust `log_max_file_size` or `log_max_files` before data loss occurs.

**Production recommendations:**

* `log_max_file_size`: `52428800` (50 MB)
* `log_max_files`: `50` to `100`
  This provides approximately seven to 30 days of retention depending on log volume.

**Alternative:** Reduce log verbosity instead of increasing file limits — set `log_level` to `info` or `warn` and disable `debug` on individual components. This extends retention without increasing disk usage.

## Excessive log volume

If logs rotate too quickly or consume excessive disk space, reduce verbosity and adjust rotation settings.

### Reduce verbosity

Production systems should use `info` or `warn`. Never use `trace` or `spam` in production.

Navigate to your logging configuration (see [Check the log level](#check-the-log-level) above) and set:

* `log_level`: `info` or `warn`
* `console_level`: `warn` or `error`
  Save and restart Platform.

Console logging has a higher performance impact than file logging.

### Adjust rotation settings

Total disk usage = `log_max_file_size × log_max_files`

**Production recommendation:**

* `log_max_file_size`: `52428800` (50 MB)
* `log_max_files`: `50` to `100`

### Enable structured logging

Structured logging reduces log volume compared to the standard format. Platform 2023.2 and 6.2 and later support structured logging. See [Configure logging](/itential-platform/monitor/log/configure).

## Disk space full

Check disk usage:

```bash
df -h /var/log/itential
```

Archive old rotated logs:

```bash
tar -czf itential-logs-$(date +%Y%m%d).tar.gz /var/log/itential/itential-platform.log.*
mv itential-logs-*.tar.gz /backup/location/
```

Delete rotated logs beyond index five:

```bash
rm /var/log/itential/itential-platform.log.[5-9]*
rm /var/log/itential/itential-platform.log.[1-9][0-9]*
```

Restart Platform after freeing space, then reduce `log_max_files` in your logging configuration to prevent recurrence.

## Performance issues after changing log settings

If Platform performance decreases after a logging change:

#### Check log verbosity

Check whether `log_level` or `console_level` is set to `debug` or more verbose.

#### Reset to appropriate levels

Reset to `info` or `warn` for file logging and `warn` or `error` for console logging.

#### Check component overrides

Check individual components for verbose logging overrides.

#### Monitor system resources

```bash
top
iostat -x 1
```

## Parse errors

### Mixed log formats

During structured logging migration, log files may contain both formats. Configure your parser to check for the `message` field (structured), fall back to `@message` (standard), and handle `context.legacy_args` arrays.

### Preserve JSON formatting

journalctl does not preserve JSON structure. Collect log files directly to maintain formatting:

```bash
cat /var/log/itential/itential-platform.log
```

### Validate JSON

Test that log entries are valid JSON:

```bash
cat /var/log/itential/itential-platform.log | jq '.' > /dev/null
```

If errors appear, [contact support](/itential-platform/resources/get-support) with examples and your Platform version.

> Diagnose and resolve common logging problems