tuwunel_core/config/logging.rs
1//! Configures log filtering, formatting, and output.
2//!
3//! Console and journal settings select destinations and presentation.
4//! Low-level initialization controls support developer and expert use.
5
6use serde::Deserialize;
7use tuwunel_macros::config_example_generator;
8
9use super::true_fn;
10
11/// Logging
12///
13/// Controls what the server logs and where the output goes. By default it
14/// logs at `info` (`debug` in debug builds) to standard output with colors;
15/// under systemd it writes straight to the journal instead, keeping each
16/// line's severity.
17///
18/// Tips:
19/// - Release builds, including the published packages, compile out `debug`
20/// and `trace` events (the default `release_max_log_level` Cargo feature),
21/// so a more verbose `filter` shows nothing more until you rebuild without
22/// that feature.
23/// - A malformed `filter` stops startup. To change the filter on a running
24/// server, use `!admin debug change-log-level <filter>`; `--reset` in
25/// place of a filter restores the configured one.
26#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
27#[derive(Clone, Debug, Deserialize)]
28#[config_example_generator(
29 filename = "tuwunel-example.toml",
30 section = "global.logging",
31 group = "true"
32)]
33pub struct Logging {
34 /// Sets the maximum log level, accepting debug, info, warn, or error.
35 ///
36 /// The filter also accepts [tracing-subscriber
37 /// directives](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives).
38 /// Release builds with `release_max_log_level` omit debug and trace levels
39 /// to reduce compiled tracing overhead; debug builds do not apply that
40 /// release cap.
41 ///
42 /// default: "info"
43 /// legacy: log
44 #[serde(default = "default_filter")]
45 pub filter: String,
46
47 /// Adds ANSI colors to log output.
48 ///
49 /// Colors are suppressed for journald submissions because it treats
50 /// control bytes in formatted lines as binary instead of text.
51 ///
52 /// legacy: log_colors log_colours
53 #[serde(default = "true_fn", alias = "log_colours")]
54 pub colors: bool,
55
56 /// Selects the compact log format.
57 ///
58 /// legacy: log_compact
59 #[serde(default)]
60 pub compact: bool,
61
62 /// Selects span events included in log output.
63 ///
64 /// default: "none"
65 /// legacy: log_span_events
66 #[serde(default = "default_span_events")]
67 pub span_events: String,
68
69 /// Allows the log EnvFilter to match values using regular expressions.
70 ///
71 /// This controls `TUWUNEL_LOG` filter matching; see the
72 /// [tracing-subscriber directives
73 /// documentation](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives).
74 ///
75 /// default: true
76 /// legacy: log_filter_regex
77 #[serde(default = "true_fn")]
78 pub filter_regex: bool,
79
80 /// Displays thread IDs in tracing log output.
81 ///
82 /// default: false
83 /// legacy: log_thread_ids
84 #[serde(default)]
85 pub thread_ids: bool,
86
87 /// Redirects logging to standard error.
88 ///
89 /// The default false writes to standard output. Systemd integration
90 /// redirects to standard error as needed without this setting; this option
91 /// serves other deployments requiring redirection.
92 ///
93 /// default: false
94 /// legacy: log_to_stderr
95 #[serde(default)]
96 pub to_stderr: bool,
97
98 /// Submits logs directly to journald instead of the console when running
99 /// under systemd.
100 ///
101 /// Each entry carries its real severity as journal priority, so
102 /// `journalctl -p warning` finds warnings and errors; console capture
103 /// instead assigns one fixed priority. Messages retain console formatting
104 /// and span fields, with target, source location, and all tracing fields
105 /// attached as journal fields, the latter prefixed `F_` for queries such
106 /// as `journalctl F_ROOM_ID='!room:example.com'`. Outside systemd this has
107 /// no effect, and failure to open the journald socket retains console
108 /// output.
109 ///
110 /// default: true
111 /// legacy: log_journald
112 #[serde(default = "true_fn")]
113 pub journald: bool,
114
115 /// Initializes the logging and tracing system when enabled.
116 ///
117 /// When false the system is neither initialized nor operating, whereas an
118 /// empty `logging.filter` leaves it operating but muted. Changes have no
119 /// effect after startup. This is for developers and expert use; prefer an
120 /// empty filter to disabling the system.
121 ///
122 /// default: true
123 /// legacy: log_enable
124 #[serde(default = "true_fn")]
125 pub enable: bool,
126
127 /// Registers the configured logging and tracing system as the global
128 /// handler.
129 ///
130 /// Disabling this is a low-level developer or expert setting similar to
131 /// `logging.enable`, but the system is configured normally and only the
132 /// final global registration is omitted.
133 ///
134 /// default: true
135 /// legacy: log_global_default
136 #[serde(default = "true_fn")]
137 pub global_default: bool,
138}
139
140impl Default for Logging {
141 fn default() -> Self {
142 Self {
143 filter: default_filter(),
144 colors: true_fn(),
145 compact: Default::default(),
146 span_events: default_span_events(),
147 filter_regex: true_fn(),
148 thread_ids: Default::default(),
149 to_stderr: Default::default(),
150 journald: true_fn(),
151 enable: true_fn(),
152 global_default: true_fn(),
153 }
154 }
155}
156
157/// Returns the default log filter.
158///
159/// Debug builds use `debug`; other builds use `info`.
160#[must_use]
161pub fn default_filter() -> String {
162 cfg!(debug_assertions)
163 .then_some("debug")
164 .unwrap_or("info")
165 .to_owned()
166}
167
168/// Returns the default tracing span-event mode.
169///
170/// The value is `none`, which disables span lifecycle event emission. It is
171/// used when `logging.span_events` is omitted.
172#[must_use]
173pub fn default_span_events() -> String { "none".into() }