> 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/configure/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Configure logging

> Set log levels, rotation settings, and output formats

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](#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](#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:**

```properties
log_level=info
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:**

```properties
log_format_json=true
console_format_json=true
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:**

```properties
log_directory=/var/log/itential
log_filename=itential-platform.log
log_max_file_size=52428800
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:**

```properties
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):**

```properties
log_level=info
console_level=warn
log_format_json=true
console_format_json=false
log_max_file_size=52428800
log_max_files=50
log_directory=/var/log/itential
```

**Environment variables:**

```bash
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):**

```json
{
  "loggerProps": {
    "log_level": "info",
    "console_level": "warn",
    "log_format_json": true,
    "log_max_file_size": 52428800,
    "log_max_files": 50
  }
}
```

### Development environment

Provides detailed diagnostic output:

**Platform 6 (properties file):**

```properties
log_level=debug
console_level=debug
log_format_json=true
log_max_file_size=10485760
log_max_files=10
```

**Environment variables:**

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

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

```json
{
  "loggerProps": {
    "log_level": "info",
    "console_level": "warn",
    "log_max_file_size": 52428800,
    "log_max_files": 50
  }
}
```

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

```properties
syslog_host=syslog.example.com
syslog_port=514
syslog_protocol=udp
syslog_facility=local0
syslog_format_json=true
```

## Next steps

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

Understand log formats and levels

#### [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

> Set log levels, rotation settings, and output formats