Skip to main content

tuwunel_core/config/
tracing.rs

1//! Configures developer tracing tools.
2//!
3//! Folded span profiles support offline visualization. Tokio-console
4//! supports runtime inspection.
5
6use serde::Deserialize;
7use tuwunel_macros::config_example_generator;
8
9/// Developer tracing tools
10///
11/// Diagnostics for developers profiling the server. Neither `tokio_console`
12/// nor `[global.tracing.flame]` does anything in the default build or the
13/// published packages, so production servers can leave `[global.tracing]`
14/// out.
15///
16/// Tips:
17/// - `tokio_console` needs a build with the `tokio_console` Cargo feature
18///   and `--cfg tokio_unstable` in `RUSTFLAGS`, and a release build must
19///   also drop the default `release_max_log_level` feature. See
20///   <https://tuwunel.chat/development.html#debugging-with-tokio-console>.
21#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
22#[derive(Clone, Debug, Deserialize, Default)]
23#[config_example_generator(
24	filename = "tuwunel-example.toml",
25	section = "global.tracing",
26	group = "true",
27	ignore = "flame"
28)]
29pub struct Tracing {
30	/// Enables tokio-console for developer use as described in the
31	/// [tokio-console debugging
32	/// guide](https://tuwunel.chat/development.html#debugging-with-tokio-console).
33	///
34	/// legacy: tokio_console
35	#[serde(default)]
36	pub tokio_console: bool,
37
38	/// Settings for tracing flame.
39	///
40	/// display: section
41	#[serde(default)]
42	pub flame: Flame,
43}
44
45/// Tracing span profiles (flame graphs)
46///
47/// Profiles time spent in the server's tracing spans and writes it to a
48/// folded-stack file for flame-graph tools. Off by default, and it works only
49/// in a build with the `perf_measurements` Cargo feature, which the default
50/// build and the published packages leave out.
51///
52/// Tips:
53/// - In such a build with `enable` on, an unwritable `output_path` or a
54///   malformed `filter` stops startup.
55/// - Output is buffered, so the file is complete only after the server stops.
56#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
57#[derive(Clone, Debug, Deserialize)]
58#[config_example_generator(
59	filename = "tuwunel-example.toml",
60	section = "global.tracing.flame",
61	group = "true"
62)]
63pub struct Flame {
64	/// Collects folded stack profiles of tracing spans through tracing-flame
65	/// when the `perf_measurements` build feature is enabled, for visualization
66	/// with [inferno](https://github.com/jonhoo/inferno),
67	/// [Speedscope](https://www.speedscope.app), or other compatible tools.
68	///
69	/// legacy: tracing_flame
70	#[serde(default)]
71	pub enable: bool,
72
73	/// Selects tracing spans included in the folded stack profile.
74	///
75	/// default: "info"
76	/// legacy: tracing_flame_filter
77	#[serde(default = "default_filter")]
78	pub filter: String,
79
80	/// Selects the output path for the folded tracing-span profile.
81	///
82	/// default: "./tracing.folded"
83	/// legacy: tracing_flame_output_path
84	#[serde(default = "default_output_path")]
85	pub output_path: String,
86}
87
88impl Default for Flame {
89	fn default() -> Self {
90		Self {
91			enable: Default::default(),
92			filter: default_filter(),
93			output_path: default_output_path(),
94		}
95	}
96}
97
98fn default_filter() -> String {
99	cfg!(debug_assertions)
100		.then_some("trace,h2=off")
101		.unwrap_or("info")
102		.to_owned()
103}
104
105fn default_output_path() -> String { "./tracing.folded".to_owned() }