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
tracingsubscriber once for this process.