Operational Logging

Operational logging records diagnostics about the Relay process, including startup, configuration, plugins, gateway behavior, and runtime failures. It is separate from agent observability through ATOF, ATIF, OpenTelemetry, or OpenInference.

Relay writes operational logs to stderr. Optional file sinks receive additional copies of those records. Each record includes a root Relay ID for correlation.

Defaults

Without configuration, Relay uses:

• info as the minimum log level
• Human-readable stderr output
• No file sinks

Choose a Configuration Source

Use the source that matches how Relay is launched:

For CLI processes, Relay selects one source in this order:

1. --log-* options or --log-config-path
2. NEMO_RELAY_LOG* environment variables
3. [logging] in the resolved Relay config.toml
4. Built-in defaults

Sources are selected rather than merged. Rust applications explicitly choose which LoggingRuntime initialization method to use and do not apply the CLI precedence rules.

CLI Options

Configure the minimum level and stderr format directly:

$
nemo-relay --log-level debug --log-stderr-format jsonl

Use an absolute TOML path when file sinks or other logging settings are needed:

$
nemo-relay --log-config-path /absolute/path/to/logging.toml

Do not combine --log-config-path with --log-level or --log-stderr-format.

Environment Variables

Set these variables for the CLI or a Rust application that initializes logging with LoggingRuntime::configure_from_environment():

$
export NEMO_RELAY_LOG=debug
$
export NEMO_RELAY_LOG_STDERR_FORMAT=jsonl

Supported values are:

• NEMO_RELAY_LOG: error, warn, info, debug, or trace
• NEMO_RELAY_LOG_STDERR_FORMAT: human or jsonl

Alternatively, select an absolute TOML file:

$
export NEMO_RELAY_LOG_CONFIG_PATH=/absolute/path/to/logging.toml

NEMO_RELAY_LOG_CONFIG_PATH cannot be combined with the other logging environment variables.

TOML Configuration

Logging settings use a [logging] table:

1
[logging]
2
level = "info"
3
stderr_format = "human"
4
flush_interval_millis = 1000
5
6
[[logging.sinks]]
7
path = ".nemo-relay/logs/relay.log.jsonl"
8
format = "jsonl"
9
level = "debug"
10
queue_capacity = 1024

File sink paths are resolved relative to the process working directory. File sinks use asynchronous queues, and queue_capacity cannot exceed 8,192 entries per sink.

Rust Library API

Initialize operational logging once during application startup by choosing one of these public APIs:

• LoggingRuntime::configure(config) for a constructed LoggingConfig
• LoggingRuntime::configure_from_environment() for environment configuration
• LoggingRuntime::configure_from_file_path(path) for an absolute TOML path

For example:

1
let _logging_runtime =
2
    nemo_relay::logging::LoggingRuntime::configure_from_environment()?;

Keep the returned runtime alive until application shutdown so pending file records can be flushed.