studio_worker/
telemetry.rs

1//! Sentry telemetry — opt-in error/panic reporting.
2//!
3//! Disabled by default.  Operators enable it by setting `SENTRY_DSN`
4//! (and optionally `SENTRY_ENVIRONMENT`) before launching the worker.
5//! Nothing is hard-coded so the public repo never carries a DSN.
6//!
7//! Wiring:
8//!
9//! * `init()` reads env vars, constructs `SentryConfig`, and calls
10//!   `sentry::init`.  The returned `ClientInitGuard` must live for the
11//!   entire program — `main.rs` keeps it in a binding that drops on
12//!   shutdown, flushing any in-flight events.
13//! * `tracing_layer()` returns a `sentry-tracing` layer that maps
14//!   `error` -> Sentry event, `warn` -> breadcrumb, lower -> ignored.
15//!   Layered into the global `tracing-subscriber` registry in `main.rs`.
16//!
17//! Panic capture is on by default (the `panic` feature is part of
18//! `sentry`'s default feature set).
19use crate::{sys, RELEASE_NAME};
20use sentry_tracing::EventFilter;
21use std::borrow::Cow;
22
23/// Tracing target for telemetry events.  Stable so operators can
24/// filter with `RUST_LOG=studio_worker::telemetry=debug`.
25const TRACE_TARGET: &str = "studio_worker::telemetry";
26
27/// Fully-resolved Sentry client configuration.  Built either from the
28/// host environment (`from_env`) or — in tests — by passing inputs
29/// directly to `from_env_inner`.
30#[derive(Debug, Clone, PartialEq, Eq)]
31pub struct SentryConfig {
32    pub dsn: String,
33    pub environment: String,
34    pub release: String,
35    pub server_name: String,
36}
37
38impl SentryConfig {
39    /// Read `SENTRY_DSN` + `SENTRY_ENVIRONMENT` from the process env.
40    /// Returns `None` when no DSN is set (or it's whitespace only).
41    pub fn from_env() -> Option<Self> {
42        Self::from_env_inner(
43            std::env::var("SENTRY_DSN").ok(),
44            std::env::var("SENTRY_ENVIRONMENT").ok(),
45            RELEASE_NAME.to_string(),
46            sys::machine_name(),
47        )
48    }
49
50    /// Pure resolver used by `from_env` and the unit tests.  Keeps the
51    /// env-var plumbing isolated from the decision logic so tests don't
52    /// need to mutate process-global state.
53    pub fn from_env_inner(
54        dsn: Option<String>,
55        environment: Option<String>,
56        release: String,
57        server_name: String,
58    ) -> Option<Self> {
59        let dsn = dsn?.trim().to_string();
60        if dsn.is_empty() {
61            return None;
62        }
63        let environment = environment
64            .map(|s| s.trim().to_string())
65            .filter(|s| !s.is_empty())
66            .unwrap_or_else(|| "production".to_string());
67        Some(Self {
68            dsn,
69            environment,
70            release,
71            server_name,
72        })
73    }
74}
75
76/// Build the `sentry::ClientOptions` for a resolved config.  Returns
77/// `None` (and leaves a tracing warning) when the DSN string can't be
78/// parsed — split out from `init` so we can exercise both branches
79/// without mutating global Sentry state.
80pub fn build_client_options(cfg: &SentryConfig) -> Option<sentry::ClientOptions> {
81    let dsn = match cfg.dsn.parse() {
82        Ok(parsed) => parsed,
83        Err(e) => {
84            tracing::warn!(
85                target: TRACE_TARGET,
86                error = %e,
87                "ignoring SENTRY_DSN: not a valid sentry DSN"
88            );
89            return None;
90        }
91    };
92    Some(sentry::ClientOptions {
93        dsn: Some(dsn),
94        release: Some(Cow::Owned(cfg.release.clone())),
95        environment: Some(Cow::Owned(cfg.environment.clone())),
96        server_name: Some(Cow::Owned(cfg.server_name.clone())),
97        // We use Sentry purely for error/panic reporting; performance
98        // tracing would add network traffic for very little value on a
99        // worker that already ships structured logs.
100        traces_sample_rate: 0.0,
101        ..Default::default()
102    })
103}
104
105/// Initialise Sentry from the process environment.
106///
107/// Returns `None` when no DSN is configured, or when Sentry rejected
108/// the supplied DSN (invalid URL / unsupported scheme).  When a guard
109/// is returned, callers MUST keep it alive for the lifetime of the
110/// program — dropping it triggers a flush of pending events.
111pub fn init() -> Option<sentry::ClientInitGuard> {
112    let cfg = SentryConfig::from_env()?;
113    let options = build_client_options(&cfg)?;
114    let guard = sentry::init(options);
115    if !guard.is_enabled() {
116        tracing::warn!(
117            target: TRACE_TARGET,
118            "sentry::init returned a disabled client (likely invalid DSN); telemetry off"
119        );
120        return None;
121    }
122    tracing::info!(
123        target: TRACE_TARGET,
124        environment = %cfg.environment,
125        release = %cfg.release,
126        server_name = %cfg.server_name,
127        "sentry telemetry enabled"
128    );
129    Some(guard)
130}
131
132/// Build the `sentry-tracing` layer with our chosen severity mapping.
133///
134/// * `ERROR` -> Sentry event (operator-visible alert)
135/// * `WARN`  -> breadcrumb attached to the next event
136/// * `INFO`/`DEBUG`/`TRACE` -> ignored (too noisy for breadcrumbs;
137///   already surfaced via the structured log shipper)
138pub fn tracing_layer<S>() -> sentry_tracing::SentryLayer<S>
139where
140    S: tracing::Subscriber + for<'a> tracing_subscriber::registry::LookupSpan<'a>,
141{
142    sentry_tracing::layer().event_filter(|md| match *md.level() {
143        tracing::Level::ERROR => EventFilter::Event,
144        tracing::Level::WARN => EventFilter::Breadcrumb,
145        _ => EventFilter::Ignore,
146    })
147}
148
149#[cfg(test)]
150mod tests {
151    use super::*;
152    use crate::test_support::capture;
153
154    fn sample_config(dsn: &str) -> SentryConfig {
155        SentryConfig {
156            dsn: dsn.to_string(),
157            environment: "staging".into(),
158            release: "studio-worker@9.9.9".into(),
159            server_name: "rig-01".into(),
160        }
161    }
162
163    #[test]
164    fn build_client_options_carries_release_environment_and_server_name() {
165        let cfg = sample_config("https://abc123@o1.ingest.sentry.io/42");
166        let opts = build_client_options(&cfg).expect("a valid DSN must yield options");
167        assert!(opts.dsn.is_some(), "the parsed DSN must be attached");
168        assert_eq!(opts.release.as_deref(), Some("studio-worker@9.9.9"));
169        assert_eq!(opts.environment.as_deref(), Some("staging"));
170        assert_eq!(opts.server_name.as_deref(), Some("rig-01"));
171        // Performance tracing stays off on the worker — it already ships
172        // structured logs, so sampling traces would only add network
173        // traffic (see build_client_options).
174        assert!(
175            opts.traces_sample_rate.abs() < f32::EPSILON,
176            "traces_sample_rate must be disabled (0.0), got {}",
177            opts.traces_sample_rate
178        );
179    }
180
181    #[test]
182    fn build_client_options_rejects_invalid_dsn_and_warns() {
183        // A malformed DSN must disable telemetry with a breadcrumb —
184        // never panic the worker at startup (init() propagates the
185        // None via `?`).
186        let cfg = sample_config("not-a-valid-dsn");
187        let logs = capture(move || {
188            assert!(
189                build_client_options(&cfg).is_none(),
190                "an unparseable DSN must yield no options"
191            );
192        });
193        assert!(logs.contains("WARN"), "expected WARN event, got: {logs}");
194        assert!(
195            logs.contains("studio_worker::telemetry"),
196            "expected telemetry target, got: {logs}"
197        );
198        assert!(
199            logs.contains("not a valid sentry DSN"),
200            "expected the invalid-DSN message, got: {logs}"
201        );
202    }
203
204    #[test]
205    fn from_env_inner_rejects_empty_string_after_trim() {
206        let resolved =
207            SentryConfig::from_env_inner(Some("\t \n".into()), None, "0.0.0".into(), "h".into());
208        assert!(resolved.is_none());
209    }
210
211    #[test]
212    fn from_env_inner_populates_all_fields() {
213        let cfg = SentryConfig::from_env_inner(
214            Some("https://k@example.ingest.sentry.io/1".into()),
215            Some("prod".into()),
216            "9.9.9".into(),
217            "machine".into(),
218        )
219        .expect("dsn set");
220        assert_eq!(cfg.dsn, "https://k@example.ingest.sentry.io/1");
221        assert_eq!(cfg.environment, "prod");
222        assert_eq!(cfg.release, "9.9.9");
223        assert_eq!(cfg.server_name, "machine");
224    }
225}
studio_worker/telemetry.rs

studio_worker/
telemetry.rs
