Logging overview | Itential

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

Use structured JSON logs for new deployments. They provide better security, easier parsing, and enable field-based searches in log aggregation tools like Splunk, Datadog, and Elasticsearch.

Log structure

Every log entry contains these fields:

Field	Description
`@timestamp`	Event timestamp (ISO 8601 format)
`level`	Severity: system, error, warn, info, debug, trace, spam
`origin`	Source file and line number
`message`	Human-readable description
`context`	Additional structured data
`error`	Error details (structured format only, for error/warn levels)

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.

Level	Description	Production use
`system`	Critical Platform lifecycle events (startup, shutdown, initialization)	Always logged
`error`	Unrecoverable errors requiring immediate attention	Always logged
`warn`	Recoverable issues requiring monitoring (retries, deprecation warnings)	Always logged
`info`	Normal operational messages showing application functions correctly	Recommended default
`debug`	Detailed diagnostic information for investigating specific issues	Temporary troubleshooting only
`trace`	Step-by-step execution flow including function entry/exit and variable values	Temporary troubleshooting only
`spam`	Highest verbosity with extremely frequent events (loop iterations, polling)	Not recommended

Never use debug, trace, or spam log levels in production environments. These levels generate excessive log volume and can impact performance.

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:

Set log_level to debug
Reproduce the issue
Collect logs
Return log_level to info or warn

Log file locations

Default log directories:

Platform Version	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

Check your log_directory configuration setting if logs don’t appear in default locations.

Log rotation

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

Rotation process:

Current file reaches size limit

Log file grows to configured log_max_file_size.

File renamed with suffix

Current file renamed to itential-platform.log.1, previous .1 becomes .2, and so on.

New file created

New empty itential-platform.log file created.

Oldest file deleted

If file count exceeds log_max_files, oldest file deleted.

IAG logs

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

Next steps

Configure logging

Set log levels, rotation, and output formats

View and search logs

Access and search log files

Logging best practices

Developer guidelines and security

Troubleshoot logging

Resolve common logging issues