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.

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.

Radiator UI log tables can mark a row to show which entries were logged after it; markers stay in the browser only.

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.

Startup logging controls

--heartbeat-interval sets how often process memory, CPU and AAA activity are sampled. It accepts duration units, such as 100ms; plain numbers mean milliseconds. The default is once per minute. Independently of this interval, Radiator samples process CPU and memory every 5 seconds for the lowest and highest values of each statistics interval. Set it to 0s to disable the heartbeat, including the 5-second samples. This also stops OS metric updates, so Radiator UI cannot show OS metrics in graphs.

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.

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 and direct warn and error messages have counters that increment for every occurrence, even when no row is written. Counters use the message's full namespace and remain independent of retained log rows. They keep the configured statistics history and reset when Radiator Server restarts. When the experimental alerts feature is enabled, WARN/ERROR event counters also supply automatic log alerts. Incident-aware messages instead update the backend incident. Failures and recovery attempts share one incident ID; only confirmed recovery resolves the incident. 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.

Radiator stores the context ID with each AAA log record in a memory target, so the records of one request can be correlated even when the log action does not write %{context.id}. Packets that a capture with a memory target records during AAA processing also carry the context ID, so they can be correlated with the same request.

To give Radiator support the logs held in memory together with the active configuration, download a diagnostics package.

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 recommendations on retaining logs outside the server, see Backup Policy Recommendations.

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.