Crate dig_logging 

dig-logging

The shared logging + log-collection building block for the DIG service binaries (dig-node, dig-dns, dig-updater; later dig-relay, digstore). It is the ONE place those binaries get their logging from, so the sink layout, directory convention, JSONL schema, rotation policy, level control, correlation ids, redaction rules, and logs CLI verbs are byte-identical across every binary. SPEC.md is the normative contract.

It is a thin composition over tracing, tracing_subscriber, and tracing_appender — it builds ON tracing, it does not replace it.

Quick start

let _guard = dig_logging::init(dig_logging::Service {
    name: "dig-node",
    version: env!("CARGO_PKG_VERSION"),
    run_context: dig_logging::RunContext::Service,
})?;
tracing::info!(peer = "203.0.113.7", "serving");

init installs a dual sink — a structured JSONL file (rolling daily, byte-capped, non-blocking and lossy under backpressure) plus compact human text on stderr — behind one reloadable level filter, and stamps a per-run run_id (+ op_id/parent_op_id correlation). Hold the returned LogGuard for the process lifetime.

Collection

Consumers mount the reusable logs verbs (path/tail/level/bundle) and the redact engine gives a logs bundle a safe, secret-scrubbed zip for a bug report.

Modules

logs

The reusable logs CLI verb set (SPEC §8.1).

redact

The redaction engine (SPEC §8.2) — the SECOND line of defense behind the never-log-at-source rule (SPEC §7). Applied to every line at BUNDLE time (bundle::build re-redacts the on-disk JSONL as it is zipped) so a log bundle is safe to hand to a stranger. It is NOT applied at write time — the on-disk log files hold RAW lines, and logs tail/a manual copy therefore see un-redacted text. The primary defense is source-discipline (SPEC §7, the never-log list); bundle redaction is the guaranteed chokepoint for anything sent off-box. The rule set is VERSIONED (RULES_VERSION) and recorded in every bundle manifest, so a bundle’s redaction guarantees are auditable after the fact.

Structs

LogGuard

Held by the caller for the life of the process. Dropping it flushes the file writer (SPEC §4.4); it also exposes runtime level control (SPEC §5).

Service

A binary’s identity, passed to init and the logs verbs.

Enums

Error

Everything that can go wrong initializing logging or running a logs verb.

RunContext

How the binary is running — stamped as the run_context field (SPEC §2).

Constants

DEFAULT_DIRECTIVE

The baked-in default: info, with the chattiest transport crates trimmed to warn.

ENV_DIG_LOG

The env var carrying an operator-set filter (ecosystem-common name), checked before RUST_LOG.

ENV_DIG_OP_ID

The env var a parent process sets in a child’s environment to propagate its operation id.

ENV_LOG_DIR

The env var that overrides the log ROOT outright (tests, custom deploys).

ENV_MAX_BYTES

The env var overriding the per-service-dir byte cap, default 50 MiB.

ENV_RETENTION_DAYS

The env var overriding the retention day count (tracing-appender max_log_files), default 7.

ENV_RUST_LOG

The Rust-conventional filter env var, kept working as the lowest-priority env source.

OP_ID_FIELD

The reserved span-field name a consumer uses to tag a top-level operation (SPEC §6).

Functions

init

Install the DIG logging stack for service (SPEC §1). Call ONCE at process start; a second call returns Error::AlreadyInitialized.

log_dir

The resolved service log directory for this process, wiring the real environment + a filesystem creatable-probe into resolve_log_dir.

new_run_id

Mint a fresh run id for this process run.

parent_op_id

Read the propagated parent operation id from an injected env-getter: the DIG_OP_ID value when present + non-blank, else None. Pure, so the pickup is testable without the process environment.

resolve_filter

Resolve the effective filter directive by precedence (SPEC §5): the first non-empty of persisted > dig_log > rust_log, else DEFAULT_DIRECTIVE. Whitespace-only inputs count as empty (an exported-but-blank env var must not silence logging).

resolve_log_dir

Resolve the log directory for service from an injected env-getter and a dir-creatable probe.

Type Aliases

Result

The crate’s result alias.