Logging

Overview

Radiator has application logs for server events and configurable AAA logs for authentication, authorization, and accounting data. Configure both under the logging block.

Application and AAA logs

Application logs record startup, configuration, protocol, backend, and other server events. Each message and its fields are defined by Radiator.

Radiator UI global search includes matches from the retained application log history. Select a match to open its row details. Select the full-results action to open Application Logs with the same search applied. A selected row can become unavailable when it leaves the bounded history.

AAA logs contain operator-selected data from AAA processing. Define named aaa loggers, then write to them with the log action. Application log levels do not control AAA logging. AAA log content and output are determined by the log actions and named AAA logger configuration.

Log targets

Application and AAA loggers support these targets:

Configure application targets under logging application. Configure AAA targets inside each named AAA logger.

Log levels and resource use

Use info for normal production application logging. The debug and trace levels can generate many rows and reduce throughput, especially for high-volume protocols. Set the minimum application level separately for each target with loglevel.

Logging is asynchronous and writes rows in batches. A row can remain incomplete in an actively written file for a few milliseconds.

<a id="startup-logging-controls"></a>

Startup logging controls

The --json-log-format option selects JSON for every application log target; AAA loggers retain their configured formats. When an application file target uses JSON, Radiator loads its recent rows into the in-memory history after restart. This preserves the application log history available through Radiator UI and Management API across restarts.

The --debug command-line option sets the application log level to debug. The RADIATOR_LOG_LEVEL environment variable accepts off, error, warn, info, debug, or trace; it takes precedence over --debug and configured application target levels. Log level selection does not control Rust error backtraces. Set RUST_BACKTRACE explicitly when backtraces are needed. See built-in environment variables for details.

<a id="diagnostic-secret-exposure"></a>

Diagnostic secret exposure

To expose protected values in selected protocol and backend diagnostics, set RADIATOR_LOG_LEVEL=trace and pass --unmask-secrets. Both settings are required. For example:

RADIATOR_LOG_LEVEL=trace radiator --unmask-secrets --configuration radiator-server.radconf

Diagnostic selection and secret exposure are independent. Detailed protocol and backend events use the trace level and obscure protected values by default. The trace action can select detailed AAA backend events for one request without exposing secrets. Global trace logging selects all detailed events, including wire diagnostics that occur before an AAA pipeline starts.

Secret exposure changes values, not which diagnostic events are selected. It applies one policy to RADIUS packet attributes, LDAP operations, HTTP requests and responses, SQL operations, and database connection configuration. RadiatorDB contributes connection configuration diagnostics; it does not emit SQL-style operation details.

Formats and fields

Radiator supports traditional text and JSON application log formats. JSON is recommended when logs are collected or filtered automatically.

{
  "timestamp": "2025-12-20T11:36:34.134423+02:00",
  "level": "INFO",
  "instance_id": "R00",
  "row_id": "b62e6726-24f4-4b7f-ac5f-b0c5f1597bee",
  "namespace": ["configuration"],
  "message": "Loading configuration done",
  "fields": {
    "configuration": "radiator-server.radconf"
  }
}

The equivalent traditional row is:

2025-12-20T11:36:34.134423+02:00 configuration INFO Loading configuration done (configuration=radiator-server.radconf)

Use message as the stable event identity. The namespace identifies the component that produced the row, and fields contains event-specific details. See namespaces for the hierarchy used by logs and counters. Fields can be added over time, and their order is not stable.

All timestamps use RFC 3339 and the operating system time zone. Set the TZ environment variable before starting Radiator to select another time zone:

TZ=UTC radiator --configuration ...

Target-specific format options are documented on the linked target configuration pages.

Application messages and counters

The application log message index groups documented messages by their normal level. Each message page provides its levels and short operator guidance.

Promoted application messages have counters that increment for every occurrence, even when no row is written. View counters in Radiator UI or export them through OpenMetrics. Counter paths use the same namespaces as application logs.

Log promotion

Radiator can promote selected recurring application messages to a higher level while limiting log volume. Promotion does not change or disable their counters. See logging promotion for behavior and configuration.

<a id="pipeline-trace-logging"></a> <a id="low-level-radius-packet-and-eap-message-tracing"></a>

Troubleshooting

Use the debug action to write selected values while troubleshooting a pipeline. Use the trace action to select detailed AAA backend events for individual requests without enabling global trace logging or exposing protected values.

Protect trace logs as sensitive data. Protocol and AAA trace rows can contain identities, attributes, and session details.

Log rotation

File loggers support rotation by schedule, file size, or both. They can also retain and compress default rotated files. See file logger rotation for the configuration and retention rules.

For external rotation, rename the active file with an atomic file-system operation. Radiator detects the missing active path and creates a new file. Allow outstanding rows to finish before compressing the renamed file.