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::{
57    log_dir, resolve_log_dir, resolve_log_dir_detailed, windows_operator_read_args, LogDirSource,
58    ResolvedLogDir, ENV_LOG_DIR,
59};
60pub use filter::{resolve_filter, DEFAULT_DIRECTIVE, ENV_DIG_LOG, ENV_RUST_LOG};
61pub use janitor::{ENV_MAX_BYTES, ENV_RETENTION_DAYS};
62
63/// A binary's identity, passed to [`init`] and the [`logs`] verbs.
64#[derive(Debug, Clone, Copy)]
65pub struct Service {
66    /// The service name — one of `dig-node`, `dig-dns`, `dig-updater`, … . Names the log subdir.
67    pub name: &'static str,
68    /// The binary's semver, stamped on every record (typically `env!("CARGO_PKG_VERSION")`).
69    pub version: &'static str,
70    /// Whether this is an OS-service run or an interactive CLI run.
71    pub run_context: RunContext,
72}
73
74/// How the binary is running — stamped as the `run_context` field (SPEC §2).
75#[derive(Debug, Clone, Copy, PartialEq, Eq)]
76pub enum RunContext {
77    /// An OS-service / daemon run (Windows service, systemd, launchd).
78    Service,
79    /// An interactive or CLI invocation.
80    Cli,
81}
82
83impl RunContext {
84    /// The wire string for the `run_context` field (SPEC §2).
85    pub fn as_str(self) -> &'static str {
86        match self {
87            RunContext::Service => "service",
88            RunContext::Cli => "cli",
89        }
90    }
91}
dig_logging/lib.rs

dig_logging/
lib.rs
