> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-platform/6/monitor/log/overview/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Logging overview

> Understand logging formats, levels, and when to use structured logging

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:

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

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

```json
{
  "@timestamp": "2025-12-18T13:44:54.623Z",
  "level": "system",
  "origin": "/opt/itential/platform/server/startup.js:380",
  "message": "IAP initialization complete.",
  "context": {
    "legacy_args": ["IAP initialization complete."]
  }
}
```

**Standard format:**

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

### error level

Unrecoverable errors preventing operations from completing:

**Structured JSON:**

```json
{
  "@timestamp": "2025-12-18T13:44:55.636Z",
  "level": "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",
  "context": {
    "legacy_args": ["The following requested services were not found..."]
  }
}
```

**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:**

```json
{
  "@timestamp": "2025-12-18T13:44:54.141Z",
  "level": "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",
  "context": {
    "legacy_args": ["Skipped loading duplicate module..."]
  }
}
```

**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:**

```json
{
  "@timestamp": "2025-12-18T13:44:54.625Z",
  "level": "info",
  "origin": "/opt/itential/platform/server/core/startup/LoadModules.js:152",
  "message": "Discovered modules in 419 milliseconds",
  "context": {
    "legacy_args": ["Discovered modules in 419 milliseconds"]
  }
}
```

**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:**

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

**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:

| 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.

## Gateway logs

For Itential Gateway audit logs, see the Gateway-specific documentation.

## Next steps

#### [Configure logging](/itential-platform/monitor/log/configure)

Set log levels, rotation, and output formats

#### [View and search logs](/itential-platform/monitor/log/view-and-search)

Access and search log files

#### [Logging best practices](/itential-platform/monitor/log/best-practices)

Developer guidelines and security

#### [Troubleshoot logging](/itential-platform/monitor/log/troubleshoot)

Resolve common logging issues

#### [Manage logs](/itential-platform/monitor/log/manage)

Centralize and search logs across Platform, Gateway, MongoDB, and Redis with Loki or the Elastic Stack

#### [Loki and Alloy](/itential-platform/monitor/log/loki-alloy)

Deploy, configure, secure, and troubleshoot Grafana Loki and Alloy

> Understand logging formats, levels, and when to use structured logging