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