Log storage and formatting

Overview

Radiator provides logging on both application level and per specific component. Logs can be guided to different targets and the AAA specific logs can be formatted to match your requirements.

Logs can be sent to four different targets:

Logs can be formatted as traditional log entries or as JSON-formatted logs for consumption by different systems.

Application and AAA logs

There are two types of logs in Radiator. The Application logs are application level logs and then there are configuration driven log entries that are related to the AAA functionality.

Both logging types support JSON and traditional log formats. The command line parameter --json-log-format overrides formatting to JSON even if individual logging targets don't have JSON enabled.

Application logs cover all application startup, configuration, problem situation and upsampled entries. The content of the log entries is part of the software design and can't be modified.

AAA (business) logs are fully configurable to contain whatever fields needed. These are intended for information like accounting to be pushed to an external billing system.

Log file formats

Radiator recommends using JSON log format. It becomes useful in complex logging situations, for example when doing packet level tracing.

Example of a log row written in JSON format:

{
  "timestamp": "2025-11-01T07:28:01.780557Z",
  "level": "INFO",
  "cluster_id": "C02",
  "instance_id": "R02",
  "row_id": "a38bb7e1-6d79-4d6e-bea5-864edcbb4950",
  "message": "Starting radiator server",
  "fields": {
    "version": "10.30.1",
    "commit": "2039254a",
    "branch": "main",
    "built_at": "2025-10-31T16:31:36Z",
    "cpu_target": "aarch64-apple-darwin",
    "kind": "release",
    "app_name": "radiator"
  }
}

JSON log formatting is enabled using --json-log-format. The message above was formatted with jq for better readability.

Example of a log row written in standard format:

2025-11-01T07:27:50.045246+01:00 INFO Starting radiator server (app_name=radiator branch=main built_at=2025-10-31T16:31:36Z commit=2039254a cpu_target=aarch64-apple-darwin kind=release version=10.30.1)

Both log formats contain the same information for payload. JSON adds contextual information to the log rows to help identify the source of the row (HA identifiers and row_id).

All rows have a message field, which can be used to identify the type of activity. This can be used to filter messages without having to resort to text pattern matching (regular expressions):

 "message": "Starting radiator server",

There is also a fields entry that describes the details of the log entry:

  "fields": {
    "version": "10.30.1",
    ...

For traditional log entries the fields are added to the log line:

  Starting radiator server (app_name=radiator

More fields will be added to the log entries over time. Also configurations and protocols used in communication can add fields to the log entries. Do not rely on the order of fields to stay consistent.

Log time stamps

JSON logs are RFC 3339 (ISO 8601) formatted. Standard logs are formatted using the locale of the operating system.

The time zone of the application can be set on the command line with the TZ environment variable:

TZ=UTC radiator --configuration ...

Log levels and resource usage

Radiator recommends using info log level for production environments

The more log lines written the more CPU and IO time is used. Running on trace level can decrease application throughput radically. On non-encrypted (low CPU) protocols logging can consume more resources than the actual business logic.

See log level configuration setting for details.

Log upsampling

Radiator uses log upsampling to raise some selected trace and debug level information to info and warn levels. For example every 1000th message could be upsampled. This is used to allow for production environments to be run in info, but at the same time gain some visibility to lower level events.

As an example when creating a service receiving packets there is a configuration ip-accept that lists which IP addresses we accept connectivity from. This list can potentially block a lot of unwanted traffic in case of a firewall misconfiguration. But in case of a single client misconfiguration it will drop the packets too. The notification of dropping of packets is done on log level debug.

1. Log message to debug 'Ignoring packet due to ip-accept' happens always.
2. Sampled log message is output for every 1000 messages on info level.

Example of upsample of incoming packets from trace to info (9999 packets suppressed):

{
  "timestamp": "2025-11-01T09:06:56.752640Z",
  "target": "server",
  "level": "INFO",
  "instance_id": "R00",
  "row_id": "3c4964ab-ca5b-4f67-a280-e913f847d405",
  "message": "Received packet",
  "fields": {
    "client_addr": "127.0.0.1:61405",
    "server": "RADIUS_UDP_1812",
    "clients_list": "CLIENTS_RADIUS_ALL",
    "server_addr": "0.0.0.0:1812"
  },
  "upsampled": {
    "original_level": "Trace",
    "suppressed": 9999
  }
}

All the upsampled entries are also available as counters in the API and UI for the ability to drill into abnormal situations better.

Using logs for debugging configurations

There are tools to output to the logs using the debug action from either pipelines or LUA scripts.

Log file rotation

For file logger Radiator checks once a second if the file still exists and creates a new file if the file is missing. Things to note when doing rotation:

1. mv some.log some.log.20251101. Do not use cp or other commands that are not atomic file system operations.
2. If there is an intention to immediately compress the file wait some seconds before starting compression
3. It is possible to rotate logs on hourly basis using the same logic.

Memory logger has a limited buffer for log rows. Console and Syslog do not support any way of limiting resource consumption.