View and Search Logs

  • Updated on Dec 23, 2025
  • Published on Dec 19, 2025
Prev Next

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

Default log locations:

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.

Note

Check the log_directory setting in your logging configuration if files don't appear in default locations.

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:

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+)

Structured logs separate all data into distinct, queryable fields.

{
  "@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.

{
  "@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:

# 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 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 following examples show Splunk, Elasticsearch, and Datadog, though you can use these patterns as a starting point for 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:

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

Search by error:

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

Search by date range:

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

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

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"' /var/log/itential/itential-platform.log | 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"' /var/log/itential/itential-platform.log | 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)"' /var/log/itential/itential-platform.log | 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 entire 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 multiple 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. Current file is renamed with numeric suffix (for example, itential-platform.log.1)
  2. New empty log file is created
  3. If file count exceeds log_max_files, oldest file is deleted

Next steps