tuwunel_core/config/telemetry.rs
1//! Configures optional external telemetry.
2//!
3//! Sentry handles crash reports and performance sampling. Jaeger-compatible
4//! collectors receive selected tracing spans.
5
6use serde::Deserialize;
7use tuwunel_macros::config_example_generator;
8
9use super::{Url, true_fn};
10
11/// External telemetry
12///
13/// Sends diagnostics to services outside the server. Both exporters are off
14/// by default.
15///
16/// - `[global.telemetry.sentry]`: crash, error and performance reports to a
17/// Sentry service. Included in the default build.
18/// - `[global.telemetry.jaeger]`: tracing spans to an OpenTelemetry (OTLP)
19/// collector such as Jaeger. Needs a build with the `perf_measurements`
20/// Cargo feature.
21#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
22// No Debug: secrets are reachable from this section.
23#[derive(Clone, Deserialize, Default)]
24#[config_example_generator(
25 filename = "tuwunel-example.toml",
26 section = "global.telemetry",
27 group = "true",
28 ignore = "jaeger sentry"
29)]
30pub struct Telemetry {
31 /// Settings for telemetry jaeger.
32 ///
33 /// display: section
34 #[serde(default)]
35 pub jaeger: Jaeger,
36
37 /// Settings for telemetry sentry.
38 ///
39 /// display: section
40 #[serde(default)]
41 pub sentry: Sentry,
42}
43
44/// Jaeger span export (OpenTelemetry)
45///
46/// Exports tracing spans over OTLP (gRPC) to an OpenTelemetry collector such
47/// as Jaeger. Off by default, and available only in a build with the
48/// `perf_measurements` Cargo feature; the default build and the published
49/// packages ignore these keys.
50///
51/// Tips:
52/// - There is no key for the collector address. The exporter reads the
53/// standard `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` environment variable (or
54/// `OTEL_EXPORTER_OTLP_ENDPOINT`) and otherwise sends to
55/// `http://localhost:4317`.
56/// - Spans arrive under the service name `tuwunel`.
57/// - In a `perf_measurements` build a malformed `filter` stops startup even
58/// with `enable` off.
59#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
60#[derive(Clone, Debug, Deserialize)]
61#[config_example_generator(
62 filename = "tuwunel-example.toml",
63 section = "global.telemetry.jaeger",
64 group = "true"
65)]
66pub struct Jaeger {
67 /// Enables OTLP span export for Jaeger-compatible tracing.
68 ///
69 /// A build with performance measurements installs an OpenTelemetry layer
70 /// when enabled. The default is false, and `telemetry.jaeger.filter`
71 /// selects exported spans.
72 ///
73 /// legacy: allow_jaeger
74 #[serde(default)]
75 pub enable: bool,
76
77 /// Selects tracing spans exported to Jaeger-compatible collectors.
78 ///
79 /// default: "info"
80 /// legacy: jaeger_filter
81 #[serde(default = "default_filter")]
82 pub filter: String,
83}
84
85/// Sentry error reporting
86///
87/// Reports panics, error-level log events and a sampled share of performance
88/// traces to a Sentry service. Support is in the default build, but `enable`
89/// is off, so nothing is sent until you turn it on. Settings are read once at
90/// startup; a configuration reload neither starts nor stops reporting.
91///
92/// Set `enable = true` to report. `endpoint` takes a Sentry DSN; the default
93/// DSN reports to the tuwunel project's Sentry
94/// (`o4509498990067712.ingest.us.sentry.io`). Set your own DSN to keep
95/// reports in your Sentry.
96///
97/// Tips:
98/// - Error events carry the log message and its fields, with recent `info`
99/// and `warn` log lines attached as breadcrumbs, so reports can include
100/// user IDs and room IDs.
101/// - Sentry fills its own `server_name` field with the machine's hostname
102/// unless `send_server_name` replaces it with the Matrix server name. OS
103/// and Rust version details are attached to events as well.
104/// - With `enable` on, a malformed `filter` stops startup.
105#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
106// No Debug: secrets are reachable from this section.
107#[derive(Clone, Deserialize)]
108#[config_example_generator(
109 filename = "tuwunel-example.toml",
110 section = "global.telemetry.sentry",
111 group = "true"
112)]
113pub struct Sentry {
114 /// Enables Sentry crash and panic reporting, performance monitoring, and
115 /// metrics, disabled at runtime by default and sent to the default endpoint
116 /// domain `o4509498990067712.ingest.us.sentry.io` unless overridden.
117 ///
118 /// legacy: sentry
119 #[serde(default)]
120 pub enable: bool,
121
122 /// Selects a custom Sentry reporting URL.
123 ///
124 /// display: sensitive
125 /// default: ""
126 /// legacy: sentry_endpoint
127 #[serde(default = "default_endpoint")]
128 pub endpoint: Option<Url>,
129
130 /// Includes `server_name` in Sentry crash reports and metrics.
131 ///
132 /// legacy: sentry_send_server_name
133 #[serde(default)]
134 pub send_server_name: bool,
135
136 /// Sets the fraction of performance-monitoring traces sampled by Sentry.
137 ///
138 /// When Sentry is enabled, this must be between 0.0 and 1.0 inclusive.
139 /// High values may affect performance; 0.0 disables sampling.
140 ///
141 /// default: 0.15
142 /// legacy: sentry_traces_sample_rate
143 #[serde(default = "default_traces_sample_rate")]
144 pub traces_sample_rate: f32,
145
146 /// Attaches a stack trace to Sentry reports.
147 ///
148 /// legacy: sentry_attach_stacktrace
149 #[serde(default)]
150 pub attach_stacktrace: bool,
151
152 /// Sends panics to Sentry when telemetry is enabled.
153 ///
154 /// This defaults to true, but `telemetry.sentry.enable` must also be
155 /// enabled before any data is sent.
156 ///
157 /// legacy: sentry_send_panic
158 #[serde(default = "true_fn")]
159 pub send_panic: bool,
160
161 /// Sends errors to Sentry when telemetry is enabled.
162 ///
163 /// This defaults to true but requires Sentry enablement. It applies only
164 /// in release mode and is forced false in debug mode.
165 ///
166 /// legacy: sentry_send_error
167 #[serde(default = "true_fn")]
168 pub send_error: bool,
169
170 /// Selects the tracing log level for Sentry breadcrumbs and transactions.
171 ///
172 /// default: "info"
173 /// legacy: sentry_filter
174 #[serde(default = "default_sentry_filter")]
175 pub filter: String,
176}
177
178impl Default for Jaeger {
179 fn default() -> Self {
180 Self {
181 enable: Default::default(),
182 filter: default_filter(),
183 }
184 }
185}
186
187impl Default for Sentry {
188 fn default() -> Self {
189 Self {
190 enable: Default::default(),
191 endpoint: default_endpoint(),
192 send_server_name: Default::default(),
193 traces_sample_rate: default_traces_sample_rate(),
194 attach_stacktrace: Default::default(),
195 send_panic: true_fn(),
196 send_error: true_fn(),
197 filter: default_sentry_filter(),
198 }
199 }
200}
201
202fn default_filter() -> String {
203 cfg!(debug_assertions)
204 .then_some("trace,h2=off")
205 .unwrap_or("info")
206 .to_owned()
207}
208
209fn default_endpoint() -> Option<Url> {
210 Url::try_from("https://8994b1762a6a95af9502a7900edabc4c@o4509498990067712.ingest.us.sentry.io/4509498993213440")
211 .expect("default sentry url is invalid")
212 .into()
213}
214
215fn default_traces_sample_rate() -> f32 { 0.15 }
216
217fn default_sentry_filter() -> String { "info".to_owned() }