Logging overview

Itential Platform captures operational events, errors, and diagnostic information in logs. Use logs to monitor system behavior, troubleshoot issues, and track automation workflows.

Log formats

Platform supports two output formats:

Structured JSON (Platform 2023.2 and 6.2+)

• Separate, queryable fields
• Automated parsing by log aggregation tools
• Better security and field-based searches
• Recommended for all new deployments

Standard (all versions)

• Backward compatibility
• Existing parsers
• Gradual migration from legacy systems

Log structure

Every log entry contains these fields:

Structured JSON format

Structured logs separate 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:

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 convert to structured JSON format.

Log levels

Each log level includes all higher-severity levels. Setting log_level to warn logs system, error, and warn, but excludes info, debug, trace, and spam.

Log level examples

system level

Critical platform lifecycle events:

Structured JSON:

1
{
2
  "@timestamp": "2025-12-18T13:44:54.623Z",
3
  "level": "system",
4
  "origin": "/opt/itential/platform/server/startup.js:380",
5
  "message": "IAP initialization complete.",
6
  "context": {
7
    "legacy_args": ["IAP initialization complete."]
8
  }
9
}

Standard format:

2025-12-18T13:37:19.870Z - system: message=[ 'IAP initialization complete.' ]

error level

Unrecoverable errors preventing operations from completing:

Structured JSON:

1
{
2
  "@timestamp": "2025-12-18T13:44:55.636Z",
3
  "level": "error",
4
  "origin": "/opt/itential/platform/server/startup.js:406",
5
  "message": "The following requested services were not found on the filesystem and will be skipped: @itentialopensource/adapter-jira",
6
  "context": {
7
    "legacy_args": ["The following requested services were not found..."]
8
  }
9
}

Standard format:

2025-12-18T13:37:20.885Z - error: origin=/opt/itential/platform/server/startup.js:406, message=[ 'The following requested services were not found on the filesystem and will be skipped: @itentialopensource/adapter-jira' ]

warn level

Recoverable issues requiring attention but not preventing operations:

Structured JSON:

1
{
2
  "@timestamp": "2025-12-18T13:44:54.141Z",
3
  "level": "warn",
4
  "origin": "/opt/itential/platform/server/core/startup/LoadModules.js:147",
5
  "message": "Skipped loading duplicate module @itentialopensource/adapter-jira from /opt/itential/platform/services/adapter-jira",
6
  "context": {
7
    "legacy_args": ["Skipped loading duplicate module..."]
8
  }
9
}

Standard format:

2025-12-18T13:37:19.872Z - warn: origin=/opt/itential/platform/server/core/startup/LoadModules.js:147, message=[ 'Skipped loading duplicate module @itentialopensource/adapter-jira from /opt/itential/platform/services/adapter-jira' ]

info level (recommended for production)

Normal operational events tracking progress of operations:

Structured JSON:

1
{
2
  "@timestamp": "2025-12-18T13:44:54.625Z",
3
  "level": "info",
4
  "origin": "/opt/itential/platform/server/core/startup/LoadModules.js:152",
5
  "message": "Discovered modules in 419 milliseconds",
6
  "context": {
7
    "legacy_args": ["Discovered modules in 419 milliseconds"]
8
  }
9
}

Standard format:

2025-12-18T13:37:19.872Z - info: origin=/opt/itential/platform/server/core/startup/LoadModules.js:152, message=[ 'Discovered modules in 459 milliseconds' ]

debug level

Detailed diagnostic information for troubleshooting:

Structured JSON:

1
{
2
  "@timestamp": "2025-12-18T13:44:54.651Z",
3
  "level": "debug",
4
  "origin": "/opt/itential/platform/server/core/integrations/Gateway.js:347",
5
  "message": "Gateway adding instance config api.sleeper.app"
6
}

Standard format:

2025-12-18T13:37:19.895Z - debug: origin=/opt/itential/platform/server/core/integrations/Gateway.js:347, message=[ 'Gateway adding instance config api.sleeper.app' ]

When to use each log level

Production environments

Use these levels:

• system - Always logged, not configurable
• error - Unrecoverable failures
• warn - Recoverable issues, retries, deprecations
• info - Normal operations (recommended default)

Avoid these levels:

• debug - Only during active troubleshooting
• trace - Never in production
• spam - Never in production

Development environments

Use these levels:

• debug - Default for development
• trace - Temporary deep debugging
• spam - Temporary high-frequency event tracking

Troubleshooting

Temporarily increase verbosity:

1. Set log_level to debug
2. Reproduce the issue
3. Collect logs
4. Return log_level to info or warn

Log file locations

Default log directories:

Rotated logs use numeric suffixes:

• itential-platform.log.1
• itential-platform.log.2
• And so on

Log rotation

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

Rotation process:

IAG logs

For Itential Automation Gateway (IAG) audit logs, see the IAG-specific documentation.

Next steps