Configure logging

Configure logging settings for Itential Platform, applications, and adapters through Admin Essentials or configuration files.

Before you begin

Verify your Platform version: Admin Essentials > About
Review your organization’s log retention policies
Understand log levels and their impact on performance

Version support

Feature	Platform 6.2+	Platform 6.0, 6.1	Platform 2023.2	Platform 2023.1 and earlier
Configuration via Logging page	✓	✓	✗	✗
Configuration via Profiles page	✗	✗	✓	✓
Structured JSON logging	✓	✗	✓	✗

Configure global logging

Changes require a Platform restart.

Platform 6

Navigate to logging configuration

Go to Admin Essentials > Configuration > Logging.

Configure settings

Set logging parameters. For more information, see Configuration parameters below.

Save configuration

Click Save (disk icon).

Restart Platform

Restart Itential Platform for changes to take effect.

Platform 2023.2 and earlier

Navigate to profiles

Go to Admin Essentials and expand Profiles.

Select active profile

Select the active profile (for example, profile1).

Open configuration

Click the Configure tab.

Select logger properties

Select loggerProps from the property list.

Configure settings

Set logging parameters (see Configuration parameters below).

Save configuration

Click Save (disk icon).

Restart Platform

Restart Itential Platform for changes to take effect.

Configuration parameters

Log level and output

Control minimum severity level for logs written to files and console.

Parameter	Description	Default
`log_level`	Minimum severity level for file logging. Each level includes higher-severity levels. Higher verbosity increases log volume and may impact performance.	`debug`
`console_level`	Minimum severity level for console output (stdout/stderr). Appears in container logs and terminal output.	`warn`

Environment variables:

ITENTIAL_LOG_LEVEL
ITENTIAL_LOG_LEVEL_CONSOLE

Properties file:

1 log_level=info
2 console_level=warn

Choose log levels by scenario

Scenario	`log_level`	`console_level`	Rationale
Production with log aggregation	`info`	`warn`	Detailed file logs, only important console output
Production without log aggregation	`warn`	`warn`	Minimize storage, match console
Development/debugging	`debug`	`debug`	Maximum visibility
Container orchestration	`info`	`info`	Console is the log destination

In container deployments where console logs forward to centralized logging, set both log_level and console_level to the same value.

Log format

Configure output format for logs. Structured JSON format enables automated parsing.

Parameter	Description	Default	Available
`log_format_json`	Enables structured JSON logging with separate, queryable fields.	`false`	Platform 2023.2, 6.2+
`console_format_json`	Formats console output as structured JSON. Enable when container orchestration forwards console logs to centralized logging.	`false`	Platform 2023.2, 6.2+
`syslog_format_json`	Formats syslog output as structured JSON.	`false`	Platform 2023.2, 6.2+

Environment variables:

ITENTIAL_LOG_FORMAT_JSON
ITENTIAL_CONSOLE_FORMAT_JSON
ITENTIAL_SYSLOG_FORMAT_JSON

Properties file:

1 log_format_json=true
2 console_format_json=true
3 syslog_format_json=false

Existing multi-argument log calls automatically convert to structured JSON format at runtime. You don’t need to update logging code immediately when enabling JSON format.

Log file management

Configure log file location, naming, and rotation behavior.

Parameter	Description	Default
`log_directory`	Absolute path where Platform writes log files. Directory must exist with write permissions and sufficient disk space.	`/var/log/pronghorn`
`log_filename`	Primary log file name. Rotated files append numeric suffixes.	`pronghorn.log`
`log_max_file_size`	Maximum log file size in bytes before rotation.	`10485760` (10 MB)
`log_max_files`	Number of rotated files to retain. Total disk usage ≈ `log_max_file_size × log_max_files`	`100`

Environment variables:

ITENTIAL_LOG_DIRECTORY
ITENTIAL_LOG_FILENAME
ITENTIAL_LOG_MAX_FILE_SIZE
ITENTIAL_LOG_MAX_FILES

Properties file:

1 log_directory=/var/log/itential
2 log_filename=itential-platform.log
3 log_max_file_size=52428800
4 log_max_files=50

Production recommendation:

log_max_file_size: 52428800 (50 MB)
log_max_files: 50 to 100
Provides approximately 7-30 days of retention depending on log volume

Timestamps

Configure timezone for log timestamps.

Parameter	Description	Default
`log_timezone_offset`	UTC offset in hours for log timestamps. For example, `-5` for EST or `-8` for PST.	`0` (UTC)

Environment variable: ITENTIAL_LOG_TIMEZONE_OFFSET

Properties file:

1 log_timezone_offset=-5

UTC (offset 0) is recommended for production environments to simplify log correlation across distributed systems.

Enable structured JSON logging

Structured JSON logging provides better security and easier parsing for log aggregation tools.

Requirements: Platform 2023.2 or Platform 6.2+

Navigate to logging configuration

Go to Admin Essentials > Configuration > Logging.

Enable JSON format

Set log_format_json to true.

Set appropriate log level

Set log_level to info for production environments.

Save configuration

Click Save.

Restart Platform

Restart Itential Platform for changes to take effect.

Configure component-specific logging

Override global settings for individual adapters or applications without restarting Platform.

Navigate to component

Go to Admin Essentials > Applications or Adapters.

Select component

Select the specific application or adapter.

Open logging tab

Click the Logging tab.

Set log levels

Configure:

File Log level - Minimum severity for file logging
Console Log level - Minimum severity for console output

Save changes

Click Save.

Important notes:

Changes apply immediately (no restart required)
Component reverts to global settings after Platform restart
Use for temporary troubleshooting only

Configuration examples

Production with log aggregation

Recommended for production environments with log aggregation tools:

Platform 6 (properties file):

1 log_level=info
2 console_level=warn
3 log_format_json=true
4 console_format_json=false
5 log_max_file_size=52428800
6 log_max_files=50
7 log_directory=/var/log/itential

Environment variables:

$ ITENTIAL_LOG_LEVEL=info
$ ITENTIAL_CONSOLE_LEVEL=warn
$ ITENTIAL_LOG_FORMAT_JSON=true
$ ITENTIAL_CONSOLE_FORMAT_JSON=false
$ ITENTIAL_LOG_MAX_FILE_SIZE=52428800
$ ITENTIAL_LOG_MAX_FILES=50
$ ITENTIAL_LOG_DIRECTORY=/var/log/itential

Platform 2023.2 (profile document):

1 {
2   "loggerProps": {
3     "log_level": "info",
4     "console_level": "warn",
5     "log_format_json": true,
6     "log_max_file_size": 52428800,
7     "log_max_files": 50
8   }
9 }

Development environment

Provides detailed diagnostic output:

Platform 6 (properties file):

1 log_level=debug
2 console_level=debug
3 log_format_json=true
4 log_max_file_size=10485760
5 log_max_files=10

Environment variables:

$ ITENTIAL_LOG_LEVEL=debug
$ ITENTIAL_CONSOLE_LEVEL=debug
$ ITENTIAL_LOG_FORMAT_JSON=true

Never use debug log level in production. It generates excessive log volume and can impact performance.

Container deployment

Console logs forward to centralized logging:

Environment variables:

$ ITENTIAL_LOG_LEVEL=info
$ ITENTIAL_CONSOLE_LEVEL=info
$ ITENTIAL_LOG_FORMAT_JSON=false
$ ITENTIAL_CONSOLE_FORMAT_JSON=true
$ ITENTIAL_LOG_DIRECTORY=/dev/null

Disable file logging and use JSON-formatted console output for container log forwarding.

Legacy platform (2023.1 and earlier)

For environments without structured log parsing:

Profile document:

1 {
2   "loggerProps": {
3     "log_level": "info",
4     "console_level": "warn",
5     "log_max_file_size": 52428800,
6     "log_max_files": 50
7   }
8 }

Calculate log retention

Determine retention period based on configuration:

Days of retention = (log_max_file_size × log_max_files) / estimated daily log volume

Example calculation:

log_max_file_size: 52428800 (50 MB)
log_max_files: 50
Estimated daily log volume: 100 MB

Retention = (50 MB × 50) / 100 MB per day = 25 days

Adjust retention by:

Increasing log_max_files for longer retention
Increasing log_max_file_size for fewer rotation events
Decreasing log_level verbosity to reduce daily volume

Syslog configuration

Forward logs to external syslog server:

Parameter	Description	Default
`syslog_host`	Syslog server hostname or IP	-
`syslog_port`	Syslog server port	`514`
`syslog_protocol`	Protocol (udp, tcp, tls)	`udp`
`syslog_facility`	Syslog facility	`local0`
`syslog_app_name`	Application name in syslog messages	`itential`
`syslog_format_json`	Enable JSON format for syslog	`false`

Environment variables:

ITENTIAL_SYSLOG_HOST
ITENTIAL_SYSLOG_PORT
ITENTIAL_SYSLOG_PROTOCOL
ITENTIAL_SYSLOG_FACILITY
ITENTIAL_SYSLOG_FORMAT_JSON

Properties file:

1 syslog_host=syslog.example.com
2 syslog_port=514
3 syslog_protocol=udp
4 syslog_facility=local0
5 syslog_format_json=true

Next steps

Logging overview

Understand log formats and levels

View and search logs

Access and search log files

Logging best practices

Developer guidelines and security

Troubleshoot logging

Resolve common logging issues