View and search 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

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

View log files

View recent entries

$
# 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

$
# 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

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

View rotated logs

$
# 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:

Structured JSON format (Platform 2023.2 and later)

Structured logs separate all data into distinct, queryable fields:

1
{
2
  "@timestamp": "2024-11-24T10:30:45.123Z",
3
  "level": "error",
4
  "origin": "database-service.js:89:7",
5
  "message": "Database connection failed",
6
  "context": {
7
    "userId": "user123",
8
    "operation": "getUserProfile",
9
    "retryCount": 3
10
  },
11
  "error": {
12
    "code": "ECONNREFUSED",
13
    "message": "Connection refused",
14
    "stack": "Error: Connection refused\n at..."
15
  }
16
}

Standard format

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

1
{
2
  "@timestamp": "2024-11-24T10:30:45.123Z",
3
  "level": "info",
4
  "origin": "auth-service.js:145:12",
5
  "message": "User authentication successful",
6
  "context": {
7
    "legacy_args": ["User authentication successful", "user123"]
8
  }
9
}

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:

$
# 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:

$
# 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:

$
# 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:

$
# 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:

$
journalctl -u pronghorn.service

Follow logs in real-time:

$
journalctl -f -u pronghorn.service

View logs from a specific time:

$
journalctl -u pronghorn.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:

$
# 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:

1
{
2
  "query": {
3
    "match": {
4
      "context.userId": "user123"
5
    }
6
  }
7
}

Search by error:

1
{
2
  "query": {
3
    "bool": {
4
      "must": [
5
        { "match": { "level": "error" }},
6
        { "match": { "error.code": "ECONNREFUSED" }}
7
      ]
8
    }
9
  }
10
}

Search by date range:

1
{
2
  "query": {
3
    "range": {
4
      "@timestamp": {
5
        "gte": "now-24h",
6
        "lte": "now"
7
      }
8
    }
9
  }
10
}

Datadog

Example searches:

$
# 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

Export logs

Export the current log file:

$
# 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:

$
# 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.