From d5f2b67b6439578d6c18d858051791f102d6c03f Mon Sep 17 00:00:00 2001 From: Eric Evans <194135482+ericevans-nv@users.noreply.github.com> Date: Tue, 14 Jul 2026 11:20:01 -0500 Subject: [PATCH 1/5] docs(cli): document operational process logging config Signed-off-by: Eric Evans <194135482+ericevans-nv@users.noreply.github.com> --- docs/nemo-relay-cli/basic-usage.mdx | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/nemo-relay-cli/basic-usage.mdx b/docs/nemo-relay-cli/basic-usage.mdx index 674ebed8b..871a31271 100644 --- a/docs/nemo-relay-cli/basic-usage.mdx +++ b/docs/nemo-relay-cli/basic-usage.mdx @@ -142,6 +142,27 @@ leaving the plugin editor does not remove the saved base configuration. You can open the plugin editor again later with `nemo-relay plugins edit`, or use `nemo-relay plugins edit --project` for project configuration. +### Operational Logging + +Configure Relay process logging under `[logging]` in `config.toml`. Stderr is +always enabled. Optional file sinks append asynchronously so logging cannot +block the gateway or agent on slow disk I/O. + +```toml +[logging] +level = "info" # minimum severity: error | warn | info | debug | trace +stderr_format = "human" # human | jsonl + +[[logging.sinks]] +path = ".nemo-relay/logs/relay.log.jsonl" # required; relative paths use process CWD +format = "jsonl" # optional; default jsonl (human | jsonl) +level = "debug" # optional; defaults to [logging].level + +# Advanced async file delivery (optional; omit to use defaults): +queue_capacity = 1024 # max records waiting for disk write (must be > 0) +flush_interval_millis = 1000 # periodic flush; 0 = flush only on shutdown +``` + ## Add Model Pricing for Cost Estimates Model pricing is configured with the same `plugins.toml` discovery path as From 2cc0bdc5d995057a5318f17fbc29e89e3c6c9c3f Mon Sep 17 00:00:00 2001 From: Eric Evans <194135482+ericevans-nv@users.noreply.github.com> Date: Tue, 14 Jul 2026 14:57:03 -0500 Subject: [PATCH 2/5] docs(cli): document max_queue_capacity and queue_capacity bound Signed-off-by: Eric Evans <194135482+ericevans-nv@users.noreply.github.com> --- docs/nemo-relay-cli/basic-usage.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/nemo-relay-cli/basic-usage.mdx b/docs/nemo-relay-cli/basic-usage.mdx index 871a31271..5ec0632e6 100644 --- a/docs/nemo-relay-cli/basic-usage.mdx +++ b/docs/nemo-relay-cli/basic-usage.mdx @@ -150,8 +150,9 @@ block the gateway or agent on slow disk I/O. ```toml [logging] -level = "info" # minimum severity: error | warn | info | debug | trace -stderr_format = "human" # human | jsonl +level = "info" # minimum severity: error | warn | info | debug | trace +stderr_format = "human" # human | jsonl +max_queue_capacity = 1048576 # optional; safety ceiling for each sink's queue_capacity [[logging.sinks]] path = ".nemo-relay/logs/relay.log.jsonl" # required; relative paths use process CWD @@ -159,7 +160,7 @@ format = "jsonl" # optional; default jsonl (human | jsonl) level = "debug" # optional; defaults to [logging].level # Advanced async file delivery (optional; omit to use defaults): -queue_capacity = 1024 # max records waiting for disk write (must be > 0) +queue_capacity = 1024 # max records waiting for disk write; 0 < value <= max_queue_capacity flush_interval_millis = 1000 # periodic flush; 0 = flush only on shutdown ``` From ccc0204dc3dad384b229e6a41b545732e063ac38 Mon Sep 17 00:00:00 2001 From: Eric Evans <194135482+ericevans-nv@users.noreply.github.com> Date: Wed, 15 Jul 2026 19:07:08 -0500 Subject: [PATCH 3/5] docs(cli): document logging configuration sources Signed-off-by: Eric Evans <194135482+ericevans-nv@users.noreply.github.com> --- docs/nemo-relay-cli/basic-usage.mdx | 63 ++++++++++++++++++++++++----- 1 file changed, 53 insertions(+), 10 deletions(-) diff --git a/docs/nemo-relay-cli/basic-usage.mdx b/docs/nemo-relay-cli/basic-usage.mdx index 5ec0632e6..2e533409b 100644 --- a/docs/nemo-relay-cli/basic-usage.mdx +++ b/docs/nemo-relay-cli/basic-usage.mdx @@ -144,26 +144,69 @@ open the plugin editor again later with `nemo-relay plugins edit`, or use ### Operational Logging -Configure Relay process logging under `[logging]` in `config.toml`. Stderr is -always enabled. Optional file sinks append asynchronously so logging cannot -block the gateway or agent on slow disk I/O. +Relay initializes operational logging before operational commands start. +`nemo-relay config` and `nemo-relay plugins edit` skip logging initialization so +you can repair invalid logging settings. Logs always go to stderr. Without +configuration, Relay uses `info` level, human-readable stderr output, and no +file sinks. + +Relay selects one CLI logging source in this order: + +1. `--log-*` command-line options +2. `NEMO_RELAY_LOG*` environment variables +3. `[logging]` in the resolved Relay `config.toml` +4. Built-in defaults + +Sources are not merged. Configure the level and stderr format directly: + +```bash +nemo-relay --log-level debug --log-stderr-format jsonl +``` + +Alternatively, select an absolute TOML file containing a `[logging]` section: + +```bash +nemo-relay --log-config-path /absolute/path/to/logging.toml +``` + +Environment variables provide the same two choices: + +```bash +export NEMO_RELAY_LOG=debug +export NEMO_RELAY_LOG_STDERR_FORMAT=jsonl + +# Or select an absolute TOML file instead: +export NEMO_RELAY_LOG_CONFIG_PATH=/absolute/path/to/logging.toml +``` + +Do not combine `--log-config-path` with direct logging options, or +`NEMO_RELAY_LOG_CONFIG_PATH` with the other logging environment variables. + +The standard Relay configuration uses the following schema: ```toml [logging] level = "info" # minimum severity: error | warn | info | debug | trace stderr_format = "human" # human | jsonl -max_queue_capacity = 1048576 # optional; safety ceiling for each sink's queue_capacity +flush_interval_millis = 1000 # optional; 0 flushes only during shutdown [[logging.sinks]] path = ".nemo-relay/logs/relay.log.jsonl" # required; relative paths use process CWD -format = "jsonl" # optional; default jsonl (human | jsonl) -level = "debug" # optional; defaults to [logging].level - -# Advanced async file delivery (optional; omit to use defaults): -queue_capacity = 1024 # max records waiting for disk write; 0 < value <= max_queue_capacity -flush_interval_millis = 1000 # periodic flush; 0 = flush only on shutdown +format = "jsonl" # optional; default jsonl +level = "debug" # optional; defaults to [logging].level +queue_capacity = 1024 # optional; maximum 8192 queued entries ``` +File sinks append through asynchronous queues so slow file I/O does not block +Relay. The queue limit is fixed for process safety and cannot be increased +beyond 8192 entries per sink. + +Rust library integrations can initialize the same runtime with +`LoggingRuntime::configure`, `LoggingRuntime::configure_from_environment`, or +`LoggingRuntime::configure_from_file_path`. Keep the returned runtime alive +until the operation finishes so pending file records are flushed during +shutdown. + ## Add Model Pricing for Cost Estimates Model pricing is configured with the same `plugins.toml` discovery path as From 2e8e7c29cf7286d0e420665edb9277b630b8e850 Mon Sep 17 00:00:00 2001 From: Eric Evans <194135482+ericevans-nv@users.noreply.github.com> Date: Thu, 16 Jul 2026 11:16:59 -0500 Subject: [PATCH 4/5] docs: add operational logging guide Signed-off-by: Eric Evans <194135482+ericevans-nv@users.noreply.github.com> --- docs/getting-started/configuration.mdx | 13 +- docs/getting-started/operational-logging.mdx | 126 +++++++++++++++++++ docs/nemo-relay-cli/basic-usage.mdx | 69 ++-------- 3 files changed, 144 insertions(+), 64 deletions(-) create mode 100644 docs/getting-started/operational-logging.mdx diff --git a/docs/getting-started/configuration.mdx b/docs/getting-started/configuration.mdx index a77701e5d..c67b6a771 100644 --- a/docs/getting-started/configuration.mdx +++ b/docs/getting-started/configuration.mdx @@ -8,7 +8,9 @@ position: 4 SPDX-License-Identifier: Apache-2.0 */} -NeMo Relay runtime behavior is configured through API objects and registration calls rather than a global configuration file. +Most NeMo Relay runtime behavior is configured through API objects and +registration calls rather than a global configuration file. Process-wide +operational logging also supports environment variables and TOML configuration. ## Core Runtime Setup @@ -21,6 +23,9 @@ Most applications configure NeMo Relay by: Use scope-local registration when behavior must be tied to one request, session, or agent run. +For process-wide stderr and file logging, refer to +[Operational Logging](/getting-started/operational-logging). + ## Plugin Setup Plugins use a structured plugin configuration with: @@ -50,9 +55,9 @@ plugin component to own standard exporter setup and teardown. Refer to and [Observability](/configure-plugins/observability/about) for the supported export paths. -NeMo Relay does not require application-level environment variables for normal -runtime use. Configure most behavior through API objects, registration calls, or -plugin configuration. +Outside operational logging, NeMo Relay does not require application-level +environment variables for normal runtime use. Configure most behavior through +API objects, registration calls, or plugin configuration. `OTEL_*` variables are only relevant when the underlying OpenTelemetry exporter reads endpoint settings from the environment. Prefer explicit config objects in diff --git a/docs/getting-started/operational-logging.mdx b/docs/getting-started/operational-logging.mdx new file mode 100644 index 000000000..335a57352 --- /dev/null +++ b/docs/getting-started/operational-logging.mdx @@ -0,0 +1,126 @@ +--- +title: "Operational Logging" +description: "Configure NeMo Relay operational logs through CLI options, environment variables, TOML, or Rust APIs." +position: 6 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} + +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: + +| Use Case | Configuration Source | +| --- | --- | +| Run the Relay CLI with temporary settings | `--log-*` options | +| Configure a process without a Relay config file | `NEMO_RELAY_LOG*` environment variables | +| Reuse logging settings across runs | `[logging]` in TOML | +| Embed Relay in a Rust application | `LoggingConfig` and `LoggingRuntime` | + +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: + +```bash +nemo-relay --log-level debug --log-stderr-format jsonl +``` + +Use an absolute TOML path when file sinks or other logging settings are needed: + +```bash +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()`: + +```bash +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: + +```bash +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: + +```toml +[logging] +level = "info" +stderr_format = "human" +flush_interval_millis = 1000 + +[[logging.sinks]] +path = ".nemo-relay/logs/relay.log.jsonl" +format = "jsonl" +level = "debug" +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: + +```rust +let _logging_runtime = + nemo_relay::logging::LoggingRuntime::configure_from_environment()?; +``` + +Keep the returned runtime alive until application shutdown so pending file +records can be flushed. diff --git a/docs/nemo-relay-cli/basic-usage.mdx b/docs/nemo-relay-cli/basic-usage.mdx index b44ada66d..7e5d3c1d4 100644 --- a/docs/nemo-relay-cli/basic-usage.mdx +++ b/docs/nemo-relay-cli/basic-usage.mdx @@ -144,68 +144,17 @@ open the plugin editor again later with `nemo-relay plugins edit`, or use ### Operational Logging -Relay initializes operational logging before operational commands start. -`nemo-relay config` and `nemo-relay plugins edit` skip logging initialization so -you can repair invalid logging settings. Logs always go to stderr. Without -configuration, Relay uses `info` level, human-readable stderr output, and no -file sinks. +The CLI initializes operational logging before operational commands run. +`nemo-relay config` and `nemo-relay plugins edit` skip initialization so invalid +logging settings do not prevent configuration repair. -Relay selects one CLI logging source in this order: +Configure temporary CLI settings with `--log-level` and +`--log-stderr-format`, or select an absolute TOML file with +`--log-config-path`. -1. `--log-*` command-line options -2. `NEMO_RELAY_LOG*` environment variables -3. `[logging]` in the resolved Relay `config.toml` -4. Built-in defaults - -Sources are not merged. Configure the level and stderr format directly: - -```bash -nemo-relay --log-level debug --log-stderr-format jsonl -``` - -Alternatively, select an absolute TOML file containing a `[logging]` section: - -```bash -nemo-relay --log-config-path /absolute/path/to/logging.toml -``` - -Environment variables provide the same two choices: - -```bash -export NEMO_RELAY_LOG=debug -export NEMO_RELAY_LOG_STDERR_FORMAT=jsonl - -# Or select an absolute TOML file instead: -export NEMO_RELAY_LOG_CONFIG_PATH=/absolute/path/to/logging.toml -``` - -Do not combine `--log-config-path` with direct logging options, or -`NEMO_RELAY_LOG_CONFIG_PATH` with the other logging environment variables. - -The standard Relay configuration uses the following schema: - -```toml -[logging] -level = "info" # minimum severity: error | warn | info | debug | trace -stderr_format = "human" # human | jsonl -flush_interval_millis = 1000 # optional; 0 flushes only during shutdown - -[[logging.sinks]] -path = ".nemo-relay/logs/relay.log.jsonl" # required; relative paths use process CWD -format = "jsonl" # optional; default jsonl -level = "debug" # optional; defaults to [logging].level -queue_capacity = 1024 # optional; maximum 8192 queued entries -``` - -File sinks append through asynchronous queues so slow file I/O does not block -Relay. The queue limit is fixed for process safety and cannot be increased -beyond 8192 entries per sink. - -Rust library integrations can initialize the same runtime with -`LoggingRuntime::configure`, `LoggingRuntime::configure_from_environment`, or -`LoggingRuntime::configure_from_file_path`. Keep the returned runtime alive -until the operation finishes so pending file records are flushed during -shutdown. +For defaults, source precedence, environment variables, TOML file sinks, and +Rust APIs, refer to +[Operational Logging](/getting-started/operational-logging). ## Add Model Pricing for Cost Estimates From eca5e9b1fa3862de9723e63fd888ee401a90d848 Mon Sep 17 00:00:00 2001 From: Eric Evans <194135482+ericevans-nv@users.noreply.github.com> Date: Thu, 16 Jul 2026 11:59:11 -0500 Subject: [PATCH 5/5] docs: move operational logging guide to reference Signed-off-by: Eric Evans <194135482+ericevans-nv@users.noreply.github.com> --- docs/getting-started/configuration.mdx | 2 +- docs/nemo-relay-cli/basic-usage.mdx | 2 +- docs/{getting-started => reference}/operational-logging.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) rename docs/{getting-started => reference}/operational-logging.mdx (99%) diff --git a/docs/getting-started/configuration.mdx b/docs/getting-started/configuration.mdx index c67b6a771..1745dfbb5 100644 --- a/docs/getting-started/configuration.mdx +++ b/docs/getting-started/configuration.mdx @@ -24,7 +24,7 @@ Most applications configure NeMo Relay by: Use scope-local registration when behavior must be tied to one request, session, or agent run. For process-wide stderr and file logging, refer to -[Operational Logging](/getting-started/operational-logging). +[Operational Logging](/reference/operational-logging). ## Plugin Setup diff --git a/docs/nemo-relay-cli/basic-usage.mdx b/docs/nemo-relay-cli/basic-usage.mdx index 7e5d3c1d4..5a5166f97 100644 --- a/docs/nemo-relay-cli/basic-usage.mdx +++ b/docs/nemo-relay-cli/basic-usage.mdx @@ -154,7 +154,7 @@ Configure temporary CLI settings with `--log-level` and For defaults, source precedence, environment variables, TOML file sinks, and Rust APIs, refer to -[Operational Logging](/getting-started/operational-logging). +[Operational Logging](/reference/operational-logging). ## Add Model Pricing for Cost Estimates diff --git a/docs/getting-started/operational-logging.mdx b/docs/reference/operational-logging.mdx similarity index 99% rename from docs/getting-started/operational-logging.mdx rename to docs/reference/operational-logging.mdx index 335a57352..2202fccde 100644 --- a/docs/getting-started/operational-logging.mdx +++ b/docs/reference/operational-logging.mdx @@ -1,7 +1,7 @@ --- title: "Operational Logging" description: "Configure NeMo Relay operational logs through CLI options, environment variables, TOML, or Rust APIs." -position: 6 +position: 4 --- {/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 */}