Skip to main content

Module telemetry

Module telemetry 

Source
Expand description

Structured logging, shared by all three binaries.

Before this module the workspace had no tracing, no metrics crate and no structured log anywhere: a failure in production left println! output and nothing correlatable. Everything in the operability goals — uptime monitoring, failure detection, API analytics — depends on this existing first, which is why it landed ahead of the rest of its phase.

§Three rules, and they are not style preferences

  1. Logs go to stderr, always. The CLI’s stdout is a machine-readable contract ({"ok":true,…}); a log line written there corrupts the JSON envelope an agent is parsing. with_writer(std::io::stderr) is what makes unv … --json | jq keep working with UNV_LOG=debug set.
  2. Never log a secret value. Log the fingerprint (out::fingerprint), the entry id, or the provider name — never api_key, never a password, never a session token. A log file is not encrypted and is routinely shipped somewhere else.
  3. Logging is off unless asked for. The default level is chosen by each binary, and every one of them is quiet enough that normal operation produces nothing on stderr. A secrets manager that chatters is a secrets manager whose output nobody reads.

§Configuring it

VariableEffect
UNV_LOGtracing filter directive (info, unv_server=debug, …). Checked first.
RUST_LOGSame, checked only when UNV_LOG is unset, so an unrelated RUST_LOG in the environment still works.
UNV_LOG_FORMATjson for one JSON object per line; anything else is the human format.

An unparseable filter falls back to the caller’s default rather than panicking: a typo in an environment variable must not stop a server booting.

Functions§

init
Installs the process-wide subscriber. Safe to call more than once; only the first call has any effect.
is_initialised
True once init has run in this process. Tests use it; nothing else should need to ask.