Skip to main content

Module diagnostics

Module diagnostics 

Source
Expand description

Process-local diagnostic subscriber for the CLI entry path.

§Binary vs library

Product modules (http, cache, docs_rs, …) only emit events/spans. Global subscriber installation happens once on the process entry path (crate::run / crate::run_with_io), not from pure library helpers.

§Agent-first sinks

  • stdout: structured command output (JSON/Markdown) — never diagnostics
  • stderr: tracing events, progress lines, human errors

File rotation (tracing-appender), OpenTelemetry/OTLP, reload::Layer admin endpoints, and tokio-console are out of scope for this one-shot CLI: there is no long-lived process, no admin surface, and no product telemetry export. Diagnostics stay on stderr for agent capture.

§Targets

Events use module paths under docsrs_cli::… (e.g. docsrs_cli::http, docsrs_cli::cache, docsrs_cli::diagnostics). Steer them with -v / -q or with the XDG key log_directive (e.g. log_directive = "docsrs_cli=debug,docsrs_cli::http=trace").

§No product environment variable

The filter is built from CLI flags and config.toml only. RUST_LOG is not read (ADR 0009).

This module used to call EnvFilter::try_from_default_env(), which let RUST_LOG override -q — an ambient value silently outranking an explicit flag. The practical harm is not the rule violation: it made the product unconfigurable by the product, because no docsrs-cli command could turn that stderr noise off, while doctor kept reporting (no env).

Terminal-capability variables (NO_COLOR, TERM, CLICOLOR_FORCE) are a different category and stay: they describe the device, like isatty, and never carry product configuration. See crate::platform.

Functions§

init_tracing
Install the global tracing subscriber once for this process.