dig_logging/
lib.rs

1//! # dig-logging
2//!
3//! The shared logging + log-collection building block for the DIG service binaries (`dig-node`,
4//! `dig-dns`, `dig-updater`; later `dig-relay`, `digstore`). It is the ONE place those binaries get
5//! their logging from, so the sink layout, directory convention, JSONL schema, rotation policy,
6//! level control, correlation ids, redaction rules, and `logs` CLI verbs are byte-identical across
7//! every binary. `SPEC.md` is the normative contract.
8//!
9//! It is a thin composition over [`tracing`], [`tracing_subscriber`], and [`tracing_appender`] — it
10//! builds ON `tracing`, it does not replace it.
11//!
12//! ## Quick start
13//!
14//! ```no_run
15//! let _guard = dig_logging::init(dig_logging::Service {
16//!     name: "dig-node",
17//!     version: env!("CARGO_PKG_VERSION"),
18//!     run_context: dig_logging::RunContext::Service,
19//! })?;
20//! tracing::info!(peer = "203.0.113.7", "serving");
21//! # Ok::<(), dig_logging::Error>(())
22//! ```
23//!
24//! `init` installs a dual sink — a structured JSONL file (rolling daily, byte-capped, non-blocking
25//! and lossy under backpressure) plus compact human text on `stderr` — behind one reloadable level
26//! filter, and stamps a per-run `run_id` (+ `op_id`/`parent_op_id` correlation). Hold the returned
27//! [`LogGuard`] for the process lifetime.
28//!
29//! ## Collection
30//!
31//! Consumers mount the reusable [`logs`] verbs (`path`/`tail`/`level`/`bundle`) and the [`redact`]
32//! engine gives a `logs bundle` a safe, secret-scrubbed zip for a bug report.
33
34#![forbid(unsafe_code)]
35#![warn(missing_docs)]
36
37mod bundle;
38mod correlation;
39mod dirs;
40mod error;
41mod filter;
42mod init;
43mod janitor;
44mod layer;
45mod schema;
46mod writer;
47
48pub mod logs;
49pub mod redact;
50
51pub use error::{Error, Result};
52pub use init::{init, LogGuard};
53
54// The pure building blocks worth exposing for consumers + conformance tests (SPEC §9).
55pub use correlation::{new_run_id, parent_op_id, ENV_DIG_OP_ID, OP_ID_FIELD};
56pub use dirs::{log_dir, resolve_log_dir, ENV_LOG_DIR};
57pub use filter::{resolve_filter, DEFAULT_DIRECTIVE, ENV_DIG_LOG, ENV_RUST_LOG};
58pub use janitor::{ENV_MAX_BYTES, ENV_RETENTION_DAYS};
59
60/// A binary's identity, passed to [`init`] and the [`logs`] verbs.
61#[derive(Debug, Clone, Copy)]
62pub struct Service {
63    /// The service name — one of `dig-node`, `dig-dns`, `dig-updater`, … . Names the log subdir.
64    pub name: &'static str,
65    /// The binary's semver, stamped on every record (typically `env!("CARGO_PKG_VERSION")`).
66    pub version: &'static str,
67    /// Whether this is an OS-service run or an interactive CLI run.
68    pub run_context: RunContext,
69}
70
71/// How the binary is running — stamped as the `run_context` field (SPEC §2).
72#[derive(Debug, Clone, Copy, PartialEq, Eq)]
73pub enum RunContext {
74    /// An OS-service / daemon run (Windows service, systemd, launchd).
75    Service,
76    /// An interactive or CLI invocation.
77    Cli,
78}
79
80impl RunContext {
81    /// The wire string for the `run_context` field (SPEC §2).
82    pub fn as_str(self) -> &'static str {
83        match self {
84            RunContext::Service => "service",
85            RunContext::Cli => "cli",
86        }
87    }
88}
dig_logging/lib.rs

dig_logging/
lib.rs
