Skip to main content

degenbot_cli/
sinks.rs

1//! The telemetry sinks + boot order (ADR-043, ADR-051 D2/D9).
2//!
3//! The `#[pymodule]` init registers symbols only; the Python driver installs
4//! its subscriber in `driver_boot()`. This module installs the console's
5//! subscriber with the standalone-Rust-consumer default, so a one-shot
6//! command is silent at `info` unless an explicit `RUST_LOG` says otherwise:
7//!
8//! 1. **Typed config first.** `BotConfigLoader` (schema defaults + the
9//!    standard file layer + `DEGENBOT_*` env) is installed into the typed
10//!    holder BEFORE any subscriber exists, so `telemetry.log_level` /
11//!    `telemetry.diag` are the values the filter resolution actually sees. An
12//!    invalid config is a loud boot refusal (exit 2), exactly as Python's
13//!    module init refuses.
14//! 2. **The tracing registry.** A `fmt` layer on stderr filtered by
15//!    [`resolve_filters`](degenbot_bot::telemetry::resolve_filters) with the
16//!    Python-driver wiring default (`info`) - the same resolution the binding
17//!    boots, so an explicit `RUST_LOG` wins verbatim on this sink too - plus
18//!    the [`progress`](crate::progress) bar layer (ADR-051 D9).
19//! 3. **The shared ADR-043 contracts**: `warn_retired_env_names`,
20//!    `install_panic_hook`. The worker-census boot table is NOT dumped here —
21//!    it belongs to the drivers' boot prelude, not a one-shot command.
22//!
23//! OTLP/metrics are deliberately NOT booted here: a console invocation is a
24//! short-lived process, not a scrape target, and the Python driver's OTLP layer
25//! belongs to the long-running bot process. `telemetry.otel` is still honored as
26//! config (the typed loader refuses a bad value) - it just has no sink to gate.
27
28use std::sync::Arc;
29
30use degenbot_bot::telemetry as bot_telemetry;
31use tracing_subscriber::layer::{Layer as _, SubscriberExt as _};
32use tracing_subscriber::EnvFilter;
33
34use crate::progress::{Layer as ProgressLayer, Painter};
35
36/// The process-lifetime telemetry handles. Dropping it clears the progress bar.
37#[derive(Debug)]
38#[must_use = "the boot guard must outlive the command run"]
39pub struct TelemetryBoot {
40    painter: Arc<Painter>,
41}
42
43impl Drop for TelemetryBoot {
44    fn drop(&mut self) {
45        self.painter.finish();
46    }
47}
48
49/// Boot the console's telemetry sinks (see the module docs for the order).
50///
51/// # Errors
52///
53/// The refusal message when the typed configuration is invalid - the process
54/// cannot honor a policy it does not have, so the boot is refused exactly as
55/// the Python module init refuses it.
56pub fn boot() -> Result<TelemetryBoot, String> {
57    // Step 1: the typed config. The loader is the ONE env-reading site.
58    match degenbot_config::BotConfigLoader::new()
59        .with_standard_file_paths()
60        .load()
61    {
62        Ok(loaded) => {
63            // First-wins, mirroring the Python boot path.
64            let _ = degenbot_substrate::stance::install(Arc::new(loaded.config));
65        }
66        Err(error) => return Err(format!("invalid configuration - boot refused: {error}")),
67    }
68
69    // Step 2: the console filter. The module init no longer installs a
70    // subscriber, so THIS install is the process's one telemetry surface and
71    // it resolves with the standalone-Rust-consumer default (ADR-043 §6):
72    // silent at `info`, loud through an explicit RUST_LOG. The Python driver
73    // resolves ITS console filter in driver_boot() with its own default.
74    let plan = bot_telemetry::resolve_filters(bot_telemetry::CONSOLE_WIRING_DEFAULT_RUST);
75    let painter = Arc::new(Painter::console());
76    let console_filter = EnvFilter::new(&plan.console);
77    let subscriber = tracing_subscriber::registry()
78        .with(
79            tracing_subscriber::fmt::layer()
80                .compact()
81                .with_writer(std::io::stderr)
82                .with_filter(console_filter),
83        )
84        // No console filter on the progress layer: it self-filters by target
85        // and level (the two chunk-committed targets at INFO), so the bar and
86        // the redirected-stdout record observe chunks regardless of how quiet
87        // the log sink's default is.
88        .with(ProgressLayer::new(Arc::clone(&painter)));
89    let installed = tracing::subscriber::set_global_default(subscriber).is_ok();
90
91    // Step 3: the shared ADR-043 section 2/5 contracts. The census boot
92    // table belongs to the drivers' boot prelude — a one-shot command arms
93    // BOOT_DUMPED by dumping it, which would re-classify every later
94    // registration as a late-registration notice; the register() entries
95    // still document this process's spawn sites either way.
96    degenbot_core::telemetry::warn_retired_env_names();
97    degenbot_core::telemetry::install_panic_hook();
98
99    // The substrate's telemetry port delegates to this crate's instruments
100    // registry (see `degenbot_bot::instruments`).
101    degenbot_bot::instruments::install_substrate_telemetry_port();
102
103    degenbot_core::op_debug!(
104        domain = pump,
105        console = %plan.console,
106        "telemetry boot complete"
107    );
108    if !installed {
109        degenbot_core::op_warn!(
110            domain = pump,
111            "global tracing subscriber already installed; console wiring left untouched"
112        );
113    }
114
115    Ok(TelemetryBoot { painter })
116}