Troubleshoot logging

Diagnose and resolve common logging problems in Itential Platform.

Before you begin

• Administrator access to Itential Platform
• Your Platform version (check Admin Essentials → About)
• Familiarity with log severity levels

Collect logs for support

Choose the appropriate collection method based on whether you need JSON formatting preserved.

Collect using journalctl

First, identify your service name:

Check the running service:

$
systemctl status itential-platform

Collect all logs:

$
journalctl -u itential-platform > itential-logs-$(date +%Y%m%d).log

Collect from a time range:

$
# Last hour
$
journalctl -u itential-platform --since "1 hour ago" > logs.txt
$
 
$
# Specific range
$
journalctl -u itential-platform --since "2024-11-20 10:00:00" --until "2024-11-20 15:00:00" > logs.txt

Collect log files directly

Collect files directly from the filesystem to preserve JSON formatting:

$
# Platform 6
$
tar -czf itential-logs-$(date +%Y%m%d).tar.gz /var/log/itential/
$
 
$
# Platform 2023.2 and earlier
$
tar -czf pronghorn-logs-$(date +%Y%m%d).tar.gz /var/log/pronghorn/

Missing log messages

If expected log messages don’t appear, verify your logging configuration and directory permissions.

Check the log level

Each log level excludes lower-severity messages. Setting log_level to info excludes debug messages.

Platform 6: Navigate to Admin Essentials → Configuration → Logging and check log_level.

Platform 2023.2 and earlier: Navigate to Admin Essentials → Profiles → [your profile] → Configure → loggerProps and check log_level.

Enable verbose logging temporarily

Enable debug for a specific adapter

To minimize performance impact, enable debug logging on individual adapters rather than globally:

Check component overrides

Individual components may override global logging settings.

Verify the log directory

Ensure the log directory exists with proper permissions.

Check the directory:

$
# Platform 6
$
ls -ld /var/log/itential
$
 
$
# Platform 2023.2 and earlier
$
ls -ld /var/log/pronghorn

The directory should be owned by itential with 755 permissions. If it is missing, create it:

$
# Platform 6
$
sudo mkdir -p /var/log/itential
$
sudo chown itential:itential /var/log/itential
$
sudo chmod 755 /var/log/itential
$
 
$
# Platform 2023.2 and earlier
$
sudo mkdir -p /var/log/pronghorn
$
sudo chown itential:itential /var/log/pronghorn
$
sudo chmod 755 /var/log/pronghorn

Restart Platform after creating the directory.

Check the system journal

Check the system journal for logging initialization errors or permission issues:

$
journalctl -u itential-platform --since "10 minutes ago"

Look for permission problems, configuration errors, or disk space constraints.

Logs missing from a specific time period

If logs from a specific time period are missing, rotation may have deleted them before you could retrieve them.

Check rotation settings

Platform 6: Admin Essentials → Configuration → Logging — check log_max_file_size and log_max_files.

Platform 2023.2 and earlier: Admin Essentials → Profiles → [your profile] → Configure → loggerProps — check log_max_file_size and log_max_files.

Calculate retention period

Use this formula to estimate how many days of logs your current settings retain:

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

Example:

• log_max_file_size: 10485760 (10 MB)
• log_max_files: 10
• Estimated daily log volume: 50 MB
• Retention = (10 MB × 10) / 50 MB per day = two days

Increase retention

Adjust log_max_file_size or log_max_files before data loss occurs.

Production recommendations:

• log_max_file_size: 52428800 (50 MB)
• log_max_files: 50 to 100 This provides approximately seven to 30 days of retention depending on log volume.

Alternative: Reduce log verbosity instead of increasing file limits — set log_level to info or warn and disable debug on individual components. This extends retention without increasing disk usage.

Excessive log volume

If logs rotate too quickly or consume excessive disk space, reduce verbosity and adjust rotation settings.

Reduce verbosity

Production systems should use info or warn. Never use trace or spam in production.

Navigate to your logging configuration (see Check the log level above) and set:

• log_level: info or warn
• console_level: warn or error Save and restart Platform.

Adjust rotation settings

Total disk usage = log_max_file_size × log_max_files

Production recommendation:

• log_max_file_size: 52428800 (50 MB)
• log_max_files: 50 to 100

Enable structured logging

Structured logging reduces log volume compared to the standard format. Platform 2023.2 and 6.2 and later support structured logging. See Configure logging.

Disk space full

Check disk usage:

$
df -h /var/log/itential

Archive old rotated logs:

$
tar -czf itential-logs-$(date +%Y%m%d).tar.gz /var/log/itential/itential-platform.log.*
$
mv itential-logs-*.tar.gz /backup/location/

Delete rotated logs beyond index five:

$
rm /var/log/itential/itential-platform.log.[5-9]*
$
rm /var/log/itential/itential-platform.log.[1-9][0-9]*

Restart Platform after freeing space, then reduce log_max_files in your logging configuration to prevent recurrence.

Performance issues after changing log settings

If Platform performance decreases after a logging change:

$
top
$
iostat -x 1

Parse errors

Mixed log formats

During structured logging migration, log files may contain both formats. Configure your parser to check for the message field (structured), fall back to @message (standard), and handle context.legacy_args arrays.

Preserve JSON formatting

journalctl does not preserve JSON structure. Collect log files directly to maintain formatting:

$
cat /var/log/itential/itential-platform.log

Validate JSON

Test that log entries are valid JSON:

$
cat /var/log/itential/itential-platform.log | jq '.' > /dev/null

If errors appear, contact support with examples and your Platform version.