Skip to main content

tracing_declarative/
lib.rs

1//! tracing-declarative — Declarative tracing initialization via `tracing.toml`.
2//!
3//! # Quick start
4//!
5//! Create a `tracing.toml` in your project root:
6//!
7//! ```toml
8//! [global]
9//! level = "info"
10//! ansi = true
11//!
12//! [filter]
13//! default_level = "info"
14//!
15//! [[appender]]
16//! name = "stdout"
17//! kind = "stdout"
18//! enabled = true
19//!
20//! [appender.formatter]
21//! type = "logback"
22//! pattern = "%d [%thread] %-5level %logger{36} - %msg%n"
23//! ```
24//!
25//! Then initialize in your `main`:
26//!
27//! ```no_run
28//! tracing_declarative::init().expect("tracing init failed");
29//! tracing::info!("application started");
30//! ```
31//!
32//! # Configuration search path
33//!
34//! `init()` looks for `tracing.toml` in this order:
35//! 1. `TRACING_CONFIG` environment variable
36//! 2. `./tracing.toml` (current working directory)
37//! 3. `./tracing.toml` (executable directory)
38//!
39//! If no file is found, a built-in default is used (INFO level, stdout,
40//! default formatter).
41//!
42//! # Feature flags
43//!
44//! - **`hot-reload`** (default) — File-watch support (unstable; `tracing`
45//!   does not support re-initialization, so this is a no-op in practice).
46//! - **`opentelemetry`** — OpenTelemetry OTLP trace export via HTTP/protobuf.
47//!
48//! # Supported formatter engines
49//!
50//! | `type`      | Syntax                     | Module                      |
51//! |-------------|---------------------------|------------------------------|
52//! | `"default"` | tracing-subscriber built-in| `formatter::default`         |
53//! | `"logback"` | logback conversion words  | `formatter::logback`         |
54//! | `"log4j"`   | log4j PatternLayout       | `formatter::log4j`           |
55
56#![deny(missing_docs)]
57
58use std::io::Write as IoWrite;
59use std::path::Path;
60
61use tracing_appender::rolling::RollingFileAppender;
62use tracing_subscriber::fmt::writer::MakeWriter;
63use tracing_subscriber::layer::SubscriberExt;
64use tracing_subscriber::util::SubscriberInitExt;
65use tracing_subscriber::EnvFilter;
66
67use crate::config::{AppenderConfig, Config};
68use crate::error::ConfigError;
69use crate::formatter::build_formatter;
70use crate::sampling::SamplingWriter;
71use crate::span_fields::SpanFieldsLayer;
72
73/// Appender module (currently empty — logic lives in `lib.rs`).
74pub mod appender;
75/// Configuration structures parsed from `tracing.toml`.
76pub mod config;
77/// Error types.
78pub mod error;
79/// Formatter engines (default, logback, log4j).
80pub mod formatter;
81/// Sampling / rate-limiting writer.
82pub mod sampling;
83/// Span field capture layer (`%X{key}` / `%mdc` support).
84pub mod span_fields;
85/// Windows console ANSI support.
86pub mod windows;
87
88/// OpenTelemetry integration (feature-gated).
89#[cfg(feature = "opentelemetry")]
90pub mod otel;
91
92/// Hot-reload support (unstable — see module docs).
93#[cfg(feature = "hot-reload")]
94pub mod hot_reload;
95
96// Build-time version info injected by build.rs
97include!(concat!(env!("OUT_DIR"), "/version.rs"));
98
99/// Re-export of `ReloadHandle` when `hot-reload` feature is enabled.
100#[cfg(feature = "hot-reload")]
101pub use hot_reload::ReloadHandle;
102
103#[cfg(feature = "opentelemetry")]
104use otel::build_otel_layer;
105
106/// Initialize tracing from the default `tracing.toml` search path.
107///
108/// # Example
109///
110/// ```no_run
111/// tracing_declarative::init().expect("tracing init failed");
112/// tracing::info!("hello");
113/// ```
114///
115/// # Errors
116///
117/// Returns an error if the config file exists but cannot be parsed,
118/// or if an appender cannot be created (e.g. invalid rolling file path).
119pub fn init() -> Result<(), ConfigError> {
120    let config = Config::from_default_file()?;
121    init_with_config(config)
122}
123
124/// Initialize tracing from a specific file path.
125///
126/// # Example
127///
128/// ```no_run
129/// tracing_declarative::init_from_file("/etc/myapp/tracing.toml")
130///     .expect("tracing init failed");
131/// ```
132pub fn init_from_file(path: impl AsRef<Path>) -> Result<(), ConfigError> {
133    let config = Config::from_file(path)?;
134    init_with_config(config)
135}
136
137/// Initialize tracing from a TOML string.
138///
139/// Useful for embedded configs or tests.
140///
141/// # Example
142///
143/// ```
144/// let config = r#"
145/// [global]
146/// level = "debug"
147///
148/// [[appender]]
149/// name = "stdout"
150/// kind = "stdout"
151/// enabled = true
152///
153/// [appender.formatter]
154/// type = "default"
155/// "#;
156/// tracing_declarative::init_from_str(config).expect("tracing init failed");
157/// ```
158pub fn init_from_str(content: &str) -> Result<(), ConfigError> {
159    let config: Config = toml::from_str(content)?;
160    init_with_config(config)
161}
162
163/// Parse configuration without initializing tracing.
164///
165/// Useful for validating a config at startup or inspecting the parsed
166/// structure.
167///
168/// # Example
169///
170/// ```
171/// let config = r#"
172/// [global]
173/// level = "info"
174///
175/// [[appender]]
176/// name = "stdout"
177/// kind = "stdout"
178/// enabled = true
179/// "#;
180/// let parsed = tracing_declarative::parse(config).expect("parse failed");
181/// assert_eq!(parsed.global.level, "info");
182/// assert_eq!(parsed.appenders.len(), 1);
183/// ```
184pub fn parse(content: &str) -> Result<Config, ConfigError> {
185    let config: Config = toml::from_str(content)?;
186    Ok(config)
187}
188
189/// Try to initialize tracing from a TOML string.
190///
191/// **Deprecated:** this function has the same behavior as [`init_from_str`]
192/// because `init_with_config` already silently returns `Ok(())` when a
193/// global dispatcher has been set. Use [`init_from_str`] instead.
194#[deprecated(
195    note = "Use init_from_str instead — both functions silently skip if already initialized"
196)]
197pub fn try_init_from_str(content: &str) -> Result<(), ConfigError> {
198    let config: Config = toml::from_str(content)?;
199    init_with_config(config)
200}
201
202fn init_with_config(config: Config) -> Result<(), ConfigError> {
203    if tracing::dispatcher::has_been_set() {
204        return Ok(());
205    }
206
207    let _ = windows::enable_ansi_escapes();
208
209    let env_filter = build_env_filter(&config)?;
210
211    let enabled: Vec<&AppenderConfig> = config.appenders.iter().filter(|a| a.enabled).collect();
212    let rate = if config.sampling.enabled {
213        config.sampling.rate_per_second
214    } else {
215        0
216    };
217
218    #[cfg(feature = "opentelemetry")]
219    let otel_guard = {
220        if config.opentelemetry.enabled {
221            Some(build_otel_layer(&config.opentelemetry)?)
222        } else {
223            None
224        }
225    };
226
227    if enabled.is_empty() {
228        #[cfg(feature = "opentelemetry")]
229        if let Some(guard) = otel_guard {
230            let provider: &'static _ = Box::leak(Box::new(guard.provider));
231            let _ = provider;
232            tracing_subscriber::registry()
233                .with(guard.layer)
234                .with(env_filter)
235                .with(SpanFieldsLayer)
236                .with(tracing_subscriber::fmt::layer())
237                .try_init()
238                .ok();
239            return Ok(());
240        }
241
242        tracing_subscriber::registry()
243            .with(env_filter)
244            .with(SpanFieldsLayer)
245            .with(tracing_subscriber::fmt::layer())
246            .try_init()
247            .ok();
248        return Ok(());
249    }
250
251    let mut make_writer = MultiMakeWriter::default();
252    let mut first_formatter_cfg: Option<&crate::config::FormatterConfig> = None;
253    for appender_cfg in &enabled {
254        let factory = build_factory(appender_cfg, rate)?;
255        make_writer.push(factory);
256        if first_formatter_cfg.is_none() {
257            first_formatter_cfg = Some(&appender_cfg.formatter);
258        }
259    }
260
261    let formatter_cfg = first_formatter_cfg
262        .ok_or_else(|| ConfigError::InvalidConfig("no enabled appenders".into()))?;
263    let formatter = build_formatter(formatter_cfg)?;
264
265    #[cfg(feature = "opentelemetry")]
266    if let Some(guard) = otel_guard {
267        let provider: &'static _ = Box::leak(Box::new(guard.provider));
268        let _ = provider;
269        tracing_subscriber::registry()
270            .with(guard.layer)
271            .with(env_filter)
272            .with(SpanFieldsLayer)
273            .with(
274                tracing_subscriber::fmt::layer()
275                    .with_writer(make_writer)
276                    .event_format(formatter),
277            )
278            .try_init()
279            .ok();
280        return Ok(());
281    }
282
283    tracing_subscriber::registry()
284        .with(env_filter)
285        .with(SpanFieldsLayer)
286        .with(
287            tracing_subscriber::fmt::layer()
288                .with_writer(make_writer)
289                .event_format(formatter),
290        )
291        .try_init()
292        .ok();
293    Ok(())
294}
295
296/// Build a factory that produces a fresh `Box<dyn Write + Send>` per
297/// event, using the configured appender.
298fn build_factory(
299    appender_cfg: &AppenderConfig,
300    global_rate: u64,
301) -> Result<WriterFactory, ConfigError> {
302    let rate = if appender_sampling_enabled(appender_cfg) {
303        global_rate
304    } else {
305        0
306    };
307    let factory: WriterFactory = match appender_cfg.kind.as_str() {
308        "stdout" => make_sampler_factory(SamplingWriter::new(std::io::stdout, rate)),
309        "stderr" => make_sampler_factory(SamplingWriter::new(std::io::stderr, rate)),
310        "file" => {
311            let path = appender_cfg.path.as_ref().ok_or_else(|| {
312                ConfigError::InvalidConfig("file appender requires 'path'".into())
313            })?;
314            let file = std::fs::OpenOptions::new()
315                .create(true)
316                .write(true)
317                .append(appender_cfg.append)
318                .open(path)?;
319            make_sampler_factory(SamplingWriter::new(file, rate))
320        }
321        "rolling_file" => {
322            let dir = appender_cfg
323                .dir
324                .as_ref()
325                .ok_or(ConfigError::RollingMissingDir)?;
326            let rotation = appender_cfg.rotation.as_deref().unwrap_or("daily");
327            let rot = match rotation {
328                "daily" => tracing_appender::rolling::Rotation::DAILY,
329                "hourly" => tracing_appender::rolling::Rotation::HOURLY,
330                "never" => tracing_appender::rolling::Rotation::NEVER,
331                _ => {
332                    return Err(ConfigError::InvalidConfig(format!(
333                        "unknown rotation '{}'",
334                        rotation
335                    )));
336                }
337            };
338            let prefix = appender_cfg.prefix.as_deref().unwrap_or("app");
339            let suffix = appender_cfg.suffix.as_deref().unwrap_or("log");
340            let appender = RollingFileAppender::new(rot, dir, format!("{}.{}", prefix, suffix));
341            make_sampler_factory(SamplingWriter::new(appender, rate))
342        }
343        other => {
344            return Err(ConfigError::UnknownAppenderKind {
345                kind: other.to_string(),
346            });
347        }
348    };
349    Ok(factory)
350}
351
352fn appender_sampling_enabled(_appender_cfg: &AppenderConfig) -> bool {
353    // Per-appender sampling config is reserved for the future. For now
354    // the global rate is used for every appender.
355    true
356}
357
358/// Factory used by `MultiMakeWriter` to obtain a writer per event.
359type WriterFactory = Box<dyn Fn() -> Box<dyn IoWrite> + Send + Sync>;
360
361/// Box the `SamplingWriter` so we hold a `'static` reference, then
362/// install a closure that calls its `MakeWriter` impl per event.
363/// `Box::leak` is acceptable here because the writer lives for the
364/// remainder of the process.
365fn make_sampler_factory<W>(sampler: SamplingWriter<W>) -> WriterFactory
366where
367    W: MakeWriter<'static> + Send + Sync + 'static,
368    W::Writer: IoWrite,
369{
370    let sampler: &'static SamplingWriter<W> = Box::leak(Box::new(sampler));
371    Box::new(move || {
372        let guard = sampler.make_writer();
373        Box::new(guard) as Box<dyn IoWrite>
374    })
375}
376
377fn build_env_filter(config: &Config) -> Result<EnvFilter, ConfigError> {
378    let default_lvl = if config.filter.default_level.is_empty() {
379        config.global.level.clone()
380    } else {
381        config.filter.default_level.clone()
382    };
383
384    let mut directives = Vec::new();
385    if !default_lvl.is_empty() {
386        directives.push(default_lvl);
387    }
388    for d in &config.filter.directives {
389        directives.push(d.clone());
390    }
391    for appender in &config.appenders {
392        if appender.enabled {
393            if let Some(lvl) = &appender.level {
394                directives.push(format!("{}={}", appender.name, lvl));
395            }
396        }
397    }
398
399    let filter_str = directives.join(",");
400    if filter_str.is_empty() {
401        return EnvFilter::try_new("info").map_err(|e| ConfigError::InvalidConfig(e.to_string()));
402    }
403    EnvFilter::try_new(&filter_str).map_err(|e| ConfigError::InvalidConfig(e.to_string()))
404}
405
406/// A `MakeWriter` that fans out a single `write()` to a list of writers.
407#[derive(Default)]
408struct MultiMakeWriter {
409    factories: Vec<WriterFactory>,
410}
411
412impl MultiMakeWriter {
413    fn push(&mut self, f: WriterFactory) {
414        self.factories.push(f);
415    }
416}
417
418impl<'a> MakeWriter<'a> for MultiMakeWriter {
419    type Writer = MultiWriter;
420    fn make_writer(&'a self) -> Self::Writer {
421        let writers: Vec<Box<dyn IoWrite>> = self.factories.iter().map(|f| f()).collect();
422        MultiWriter { writers }
423    }
424}
425
426struct MultiWriter {
427    writers: Vec<Box<dyn IoWrite>>,
428}
429
430impl IoWrite for MultiWriter {
431    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
432        for w in self.writers.iter_mut() {
433            // Match the previous stdout.and(file) semantics: a failure
434            // on one writer shouldn't abort the others.
435            let _ = w.write_all(buf);
436        }
437        Ok(buf.len())
438    }
439
440    fn flush(&mut self) -> std::io::Result<()> {
441        for w in self.writers.iter_mut() {
442            let _ = w.flush();
443        }
444        Ok(())
445    }
446}