Skip to main content

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() }