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}