> 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/view-and-search/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# View and search logs

> Access and search Itential Platform logs

Access and search Itential Platform logs to monitor system behavior and troubleshoot issues.

## Before you begin

Itential Platform writes logs to files on the server. Access requires:

* SSH access to the Platform server
* Read permissions for log directories
* Basic familiarity with Linux command-line tools

## Locate log files

| Platform version            | Log directory         | Current log file        |
| --------------------------- | --------------------- | ----------------------- |
| Platform 6                  | `/var/log/itential/`  | `itential-platform.log` |
| Platform 2023.2 and earlier | `/var/log/pronghorn/` | `itential-platform.log` |

Rotated logs use numeric suffixes: `itential-platform.log.1`, `itential-platform.log.2`, and so on.

If files don't appear in the default location, check the `log_directory` setting in your logging configuration.

## View log files

### View recent entries

```bash
# Platform 6
tail -n 100 /var/log/itential/itential-platform.log
 
# Platform 2023.2 and earlier
tail -n 100 /var/log/pronghorn/itential-platform.log
```

### Follow logs in real-time

```bash
# Platform 6
tail -f /var/log/itential/itential-platform.log
 
# Platform 2023.2 and earlier
tail -f /var/log/pronghorn/itential-platform.log
```

### View entire log file

```bash
# Platform 6
cat /var/log/itential/itential-platform.log
 
# Platform 2023.2 and earlier
cat /var/log/pronghorn/itential-platform.log
```

### View rotated logs

```bash
# Platform 6
cat /var/log/itential/itential-platform.log.1
 
# Platform 2023.2 and earlier
cat /var/log/pronghorn/itential-platform.log.1
```

## Log structure

Every log entry includes these fields:

| Field        | Description                                                              |
| ------------ | ------------------------------------------------------------------------ |
| `@timestamp` | When the event occurred (ISO 8601 format)                                |
| `level`      | Severity: `system`, `error`, `warn`, `info`, `debug`, `trace`, or `spam` |
| `origin`     | Source file and line number                                              |
| `message`    | Human-readable description                                               |
| `context`    | Additional data (structure varies by format)                             |
| `error`      | Error details (structured format only, for `error` and `warn` levels)    |

### Structured JSON format (Platform 2023.2 and later)

Structured logs separate all data into distinct, queryable fields:

```json
{
  "@timestamp": "2024-11-24T10:30:45.123Z",
  "level": "error",
  "origin": "database-service.js:89:7",
  "message": "Database connection failed",
  "context": {
    "userId": "user123",
    "operation": "getUserProfile",
    "retryCount": 3
  },
  "error": {
    "code": "ECONNREFUSED",
    "message": "Connection refused",
    "stack": "Error: Connection refused\n at..."
  }
}
```

### Standard format

Standard logs embed data within message strings and use a `legacy_args` array:

```json
{
  "@timestamp": "2024-11-24T10:30:45.123Z",
  "level": "info",
  "origin": "auth-service.js:145:12",
  "message": "User authentication successful",
  "context": {
    "legacy_args": ["User authentication successful", "user123"]
  }
}
```

The `legacy_args` array appears when multi-argument log calls are automatically converted to structured JSON format.

## Search logs

### Command-line tools

Search by text:

```bash
# Platform 6
grep "authentication" /var/log/itential/itential-platform.log
 
# Platform 2023.2 and earlier
grep "authentication" /var/log/pronghorn/itential-platform.log
```

Search by log level:

```bash
# Platform 6
grep '"level":"error"' /var/log/itential/itential-platform.log
 
# Platform 2023.2 and earlier
grep '"level":"error"' /var/log/pronghorn/itential-platform.log
```

Search by date:

```bash
# Platform 6
grep "2024-11-24" /var/log/itential/itential-platform.log
 
# Platform 2023.2 and earlier
grep "2024-11-24" /var/log/pronghorn/itential-platform.log
```

Search across rotated logs:

```bash
# Platform 6
grep "database" /var/log/itential/itential-platform.log*
 
# Platform 2023.2 and earlier
grep "database" /var/log/pronghorn/itential-platform.log*
```

### systemd journal (Platform 6 only)

View all platform logs:

```bash
journalctl -u itential-platform.service
```

Follow logs in real-time:

```bash
journalctl -f -u itential-platform.service
```

View logs from a specific time:

```bash
journalctl -u itential-platform.service --since "2023-04-26 10:00:00"
```

### Log aggregation tools

Structured JSON logs integrate with log aggregation platforms without custom parsing. Configure your platform to ingest logs from the appropriate directory. The examples below use Splunk, Elasticsearch, and Datadog, but the patterns apply to any log aggregation tool.

#### Splunk

Configure Splunk to monitor:

* Platform 6: `/var/log/itential/itential-platform.log`
* Platform 2023.2 and earlier: `/var/log/pronghorn/itential-platform.log`
  Example searches:

```shell
# Search by user
index=itential context.userId="user123"
 
# Search by error
index=itential level=error
 
# Search by workflow
index=itential context.workflowName="deploy_config"
 
# Search by date range
index=itential earliest=-24h latest=now
```

#### Elasticsearch

Search by user:

```json
{
  "query": {
    "match": {
      "context.userId": "user123"
    }
  }
}
```

Search by error:

```json
{
  "query": {
    "bool": {
      "must": [
        { "match": { "level": "error" }},
        { "match": { "error.code": "ECONNREFUSED" }}
      ]
    }
  }
}
```

Search by date range:

```json
{
  "query": {
    "range": {
      "@timestamp": {
        "gte": "now-24h",
        "lte": "now"
      }
    }
  }
}
```

#### Datadog

Example searches:

```shell
# Search by user
@context.userId:user123
 
# Search by error
level:error @error.code:ECONNREFUSED
 
# Search by workflow
@context.workflowName:deploy_config
```

Use the time picker in the Datadog UI for date filtering.

## Common search patterns

| Task                       | Command line                                                                                                         | Splunk                                                  | Elasticsearch                                                                                                         | Datadog                                |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| Errors in last hour        | `grep '"level":"error"' /var/log/itential/itential-platform.log \| grep "$(date -u -d '1 hour ago' '+%Y-%m-%dT%H')"` | `index=itential level=error earliest=-1h`               | `{"query":{"bool":{"must":[{"match":{"level":"error"}},{"range":{"@timestamp":{"gte":"now-1h"}}}]}}}`                 | `level:error` (use time picker)        |
| Errors for specific user   | `grep '"level":"error"' ... \| grep '"userId":"user123"'`                                                            | `index=itential level=error context.userId="user123"`   | `{"query":{"bool":{"must":[{"match":{"level":"error"}},{"match":{"context.userId":"user123"}}]}}}`                    | `level:error @context.userId:user123`  |
| Workflow failures          | `grep '"level":"error"' ... \| grep 'workflowName'`                                                                  | `index=itential level=error context.workflowName=*`     | `{"query":{"bool":{"must":[{"match":{"level":"error"}},{"exists":{"field":"context.workflowName"}}]}}}`               | `level:error @context.workflowName:*`  |
| Database connection issues | `grep -E '"level":"(error\|warn)"' ... \| grep database`                                                             | `index=itential (level=error OR level=warn) "database"` | `{"query":{"bool":{"must":[{"query_string":{"query":"database"}}],"filter":[{"terms":{"level":["error","warn"]}}]}}}` | `(level:error OR level:warn) database` |

## Export logs

Export the current log file:

```bash
# Platform 6
cp /var/log/itential/itential-platform.log /path/to/export/itential-platform-$(date +%Y%m%d).log
 
# Platform 2023.2 and earlier
cp /var/log/pronghorn/itential-platform.log /path/to/export/itential-platform-$(date +%Y%m%d).log
```

Export all rotated logs:

```bash
# Platform 6
cp /var/log/itential/itential-platform.log* /path/to/export/
 
# Platform 2023.2 and earlier
cp /var/log/pronghorn/itential-platform.log* /path/to/export/
```

## Log rotation

Itential Platform automatically rotates log files when the current log reaches `log_max_file_size`.

During rotation:

1. The current file is renamed with a numeric suffix (for example, `itential-platform.log.1`).
2. A new empty log file is created.
3. If the file count exceeds `log_max_files`, the oldest file is deleted.

> Access and search Itential Platform logs