Skip to main content

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