docs(cli): document operational process logging config#419
Conversation
Signed-off-by: Eric Evans <194135482+ericevans-nv@users.noreply.github.com>
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughDocumentation adds a dedicated operational logging reference, clarifies CLI initialization behavior, and updates configuration guidance for logging settings, environment variables, TOML configuration, and Rust runtime initialization. ChangesOperational logging
Estimated code review effort: 1 (Trivial) | ~2 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Signed-off-by: Eric Evans <194135482+ericevans-nv@users.noreply.github.com>
Signed-off-by: Eric Evans <194135482+ericevans-nv@users.noreply.github.com>
Signed-off-by: Eric Evans <194135482+ericevans-nv@users.noreply.github.com>
Signed-off-by: Eric Evans <194135482+ericevans-nv@users.noreply.github.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/nemo-relay-cli/basic-usage.mdx`:
- Around line 153-183: Replace the logging configuration section in the basic
usage documentation with the actual observability configuration path supported
by the CLI. Remove references to --log-* options, NEMO_RELAY_LOG* variables, the
[logging] TOML table, and their precedence or mixing rules; document the real
configuration entry points and usage instead.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 798ef69d-66c9-4e56-8f4b-2db20ac26017
📒 Files selected for processing (1)
docs/nemo-relay-cli/basic-usage.mdx
📜 Review details
⏰ Context from checks skipped due to timeout. (2)
- GitHub Check: Check / Run
- GitHub Check: Preview docs
🧰 Additional context used
📓 Path-based instructions (7)
**/*.mdx
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/SKILL.md)
MDX top-of-file SPDX comments must use {/* ... */} delimiters instead of HTML comment delimiters (Must-Fix)
In MDX files, top-of-file comments must use JSX comment delimiters (
{/*to open and*/}to close); do not use HTML comments for MDX SPDX headers
Files:
docs/nemo-relay-cli/basic-usage.mdx
**/*.{md,mdx}
📄 CodeRabbit inference engine (AGENTS.md)
Update
README.md,fern/, package READMEs, and binding-support notes when public behavior, package names, examples, or supported bindings change.
**/*.{md,mdx}: Prefer the documented public API, not internal shortcuts
Keep package names, repo references, and build commands current
Keep release-process and release-notes guidance in repo-maintainer docs such asRELEASING.md, not as user-facing docs pages orCHANGELOG.md
Keep stable user-facing wrappers atscripts/root in docs and examples; only point at namespaced helper paths when documenting internal maintenance work
When detailed dynamic plugin guides exist, keep Rust native plugin examples, Python worker plugin examples, andgrpc-v1protocol details on separate pagesIf links in documentation change, run
just docs-linkcheck.
Files:
docs/nemo-relay-cli/basic-usage.mdx
**/*.{md,markdown,mdx}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Add the SPDX license header to all Markdown/MDX documentation files using the HTML comment block form.
Files:
docs/nemo-relay-cli/basic-usage.mdx
{docs,examples}/**/*
📄 CodeRabbit inference engine (.agents/skills/rename-surfaces/SKILL.md)
Update docs and examples.
Files:
docs/nemo-relay-cli/basic-usage.mdx
**/*
📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)
**/*: Format changed files with the language-native formatter before the final lint/test pass.
If dynamic plugin behavior changed, usemaintain-dynamic-pluginsand include the native SDK, worker protocol, Python SDK, docs, packaging, and Codecov surfaces in the validation plan.
If code changes alter APIs, bindings, commands, paths, packaging behavior, observability/adaptive semantics, or documented best practices, update any dependent maintainer or consumer skills in the same branch.
During iteration, preferuv run pre-commit run --files <changed files...>.
Before review or handoff, runuv run pre-commit run --all-files.
Files:
docs/nemo-relay-cli/basic-usage.mdx
docs/**/*
📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)
If documentation examples or commands under
docs/change, run the targeted docs checks appropriate to the change.
Files:
docs/nemo-relay-cli/basic-usage.mdx
{docs/**,README.md,CONTRIBUTING.md,RELEASING.md,SECURITY.md}
⚙️ CodeRabbit configuration file
{docs/**,README.md,CONTRIBUTING.md,RELEASING.md,SECURITY.md}: Review documentation for technical accuracy against the current API, command correctness, and consistency across language bindings.
Flag stale examples, missing SPDX headers where required, and instructions that no longer match CI or pre-commit behavior.
Files:
docs/nemo-relay-cli/basic-usage.mdx
🔇 Additional comments (1)
docs/nemo-relay-cli/basic-usage.mdx (1)
185-208: 🎯 Functional CorrectnessCheck the logging schema/API surface —
flush_interval_millis,queue_capacity, the 8192-entry cap, relative-path resolution, andLoggingRuntime::configure*should all map to supported public interfaces; if any of them are internal or unstable, switch this doc to the public entry point and update the defaults accordingly.
willkill07
left a comment
willkill07
left a comment
There was a problem hiding this comment.
We also need a part outside of the CLI for the environment-based configuration of logging
#### Overview Add configurable, process-wide operational logging backed by the `log` facade and `spdlog-rs`. Operational commands initialize logging during top-level dispatch, before command execution. `nemo-relay config` and `nemo-relay plugins edit` intentionally skip initialization so invalid logging configuration cannot prevent users from repairing it. This PR establishes the logging configuration and runtime. Broader production operational event call sites will be added separately. - [x] I confirm this contribution is my own work, or I have the right to submit it under this project's license. - [x] I searched existing issues and open pull requests, and this does not duplicate existing work. #### Details - Add core-owned `LoggingConfig` and `LoggingRuntime` APIs shared by CLI and library integrations. - Support built-in defaults, normal `config.toml` discovery, environment configuration, explicit absolute TOML paths, and direct CLI settings. CLI sources take precedence over environment configuration, which takes precedence over discovered file configuration and defaults. - Add an always-on stderr sink for initialized operational commands and optional asynchronous JSONL or human-readable file sinks. - Bound asynchronous file queues, reject duplicate resolved sink paths, and drain pending file records during shutdown. - Attach one root Relay ID to operational records for process-level correlation. - Keep logging output on stderr or configured files; operational logging does not write to stdout. - Keep logging configuration under `[logging]` in `config.toml`. A separate interactive logging editor is outside this PR. - Documentation for the configuration surface is tracked in #419. - Add focused core and CLI coverage for parsing, validation, formatting, sink behavior, configuration precedence, initialization policy, and shutdown flushing. - Regenerate `ATTRIBUTIONS-Rust.md` for the new Rust dependencies. #### Where should the reviewer start? - `crates/core/src/logging/` for configuration types, runtime ownership, formatting, sinks, and shutdown behavior - `crates/cli/src/commands/logging.rs` and `crates/cli/src/commands/mod.rs` for configuration-source selection and early command initialization - `crates/cli/src/configuration/logging.rs` for normal Relay TOML integration - `crates/core/tests/coverage/logging_tests.rs` and `crates/cli/tests/coverage/shared/config_tests.rs` for runtime and configuration guarantees - `crates/cli/tests/coverage/commands/main_tests.rs` for CLI precedence and command policy #### Related Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to) - Closes: RELAY-451 ## Summary by CodeRabbit * **New Features** * Added configurable operational logging with human-readable or JSONL output. * Added stderr and asynchronous file sinks with per-sink level/format, queue limits, and periodic flushing. * Introduced logging configuration via CLI options, environment variables, and TOML (including scoped application). * Logging now initializes automatically for applicable CLI commands, while configuration/editor commands can bypass it. * **Bug Fixes** * Strengthened validation for configuration values and file sink destination handling (including duplicates and invalid paths). * **Tests** * Added extensive logging coverage for config loading, formatter output, sink runtime behavior, shutdown behavior, and CLI precedence/policy. * **Chores** * Regenerated dependency attribution and license metadata. Authors: - Eric Evans II (https://github.com/ericevans-nv) - Alex Fournier (https://github.com/afourniernv) Approvers: - Alex Fournier (https://github.com/afourniernv) - Will Killian (https://github.com/willkill07) - https://github.com/Salonijain27 URL: #413
Signed-off-by: Eric Evans <194135482+ericevans-nv@users.noreply.github.com>
|
Addressed in the latest update. The standalone Operational Logging guide now documents environment-based configuration for both CLI processes and Rust applications using |
Signed-off-by: Eric Evans <194135482+ericevans-nv@users.noreply.github.com>
|
/merge |
4 participants
Overview
Documents the operational logging configuration and source-selection behavior introduced by #413. This docs-only PR should merge after or with #413 so the documented options match released CLI and library behavior.
Details
config.toml, and defaults.LoggingRuntimeentry points.[logging]and[[logging.sinks]]example for asynchronous file delivery and the fixed 8,192-entry queue safety limit.Where should the reviewer start?
docs/nemo-relay-cli/basic-usage.mdxRelated Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to)
Summary by CodeRabbit
--log-*/--log-config-path, thenNEMO_RELAY_LOG*env vars, then[logging]in resolvedconfig.toml, then defaults).OTEL_*applies) and detailed logging schema/sink options.