1 | //! A `Subscriber` for formatting and logging `tracing` data. |
2 | //! |
3 | //! # Overview |
4 | //! |
5 | //! [`tracing`] is a framework for instrumenting Rust programs with context-aware, |
6 | //! structured, event-based diagnostic information. This crate provides an |
7 | //! implementation of the [`Subscriber`] trait that records `tracing`'s `Event`s |
8 | //! and `Span`s by formatting them as text and logging them to stdout. |
9 | //! |
10 | //! # Usage |
11 | //! |
12 | //! First, add this to your `Cargo.toml` file: |
13 | //! |
14 | //! ```toml |
15 | //! [dependencies] |
16 | //! tracing-subscriber = "0.3" |
17 | //! ``` |
18 | //! |
19 | //! *Compiler support: [requires `rustc` 1.63+][msrv]* |
20 | //! |
21 | //! [msrv]: super#supported-rust-versions |
22 | //! |
23 | //! Add the following to your executable to initialize the default subscriber: |
24 | //! ```rust |
25 | //! use tracing_subscriber; |
26 | //! |
27 | //! tracing_subscriber::fmt::init(); |
28 | //! ``` |
29 | //! |
30 | //! ## Filtering Events with Environment Variables |
31 | //! |
32 | //! The default subscriber installed by `init` enables you to filter events |
33 | //! at runtime using environment variables (using the [`EnvFilter`]). |
34 | //! |
35 | //! The filter syntax is a superset of the [`env_logger`] syntax. |
36 | //! |
37 | //! For example: |
38 | //! - Setting `RUST_LOG=debug` enables all `Span`s and `Event`s |
39 | //! set to the log level `DEBUG` or higher |
40 | //! - Setting `RUST_LOG=my_crate=trace` enables `Span`s and `Event`s |
41 | //! in `my_crate` at all log levels |
42 | //! |
43 | //! **Note**: This should **not** be called by libraries. Libraries should use |
44 | //! [`tracing`] to publish `tracing` `Event`s. |
45 | //! |
46 | //! # Configuration |
47 | //! |
48 | //! You can configure a subscriber instead of using the defaults with |
49 | //! the following functions: |
50 | //! |
51 | //! ### Subscriber |
52 | //! |
53 | //! The [`FmtSubscriber`] formats and records `tracing` events as line-oriented logs. |
54 | //! You can create one by calling: |
55 | //! |
56 | //! ```rust |
57 | //! let subscriber = tracing_subscriber::fmt() |
58 | //! // ... add configuration |
59 | //! .finish(); |
60 | //! ``` |
61 | //! |
62 | //! You can find the configuration methods for [`FmtSubscriber`] in |
63 | //! [`SubscriberBuilder`]. |
64 | //! |
65 | //! ## Formatters |
66 | //! |
67 | //! The output format used by the layer and subscriber in this module is |
68 | //! represented by implementing the [`FormatEvent`] trait, and can be |
69 | //! customized. This module provides a number of formatter implementations: |
70 | //! |
71 | //! * [`format::Full`]: The default formatter. This emits human-readable, |
72 | //! single-line logs for each event that occurs, with the current span context |
73 | //! displayed before the formatted representation of the event. See |
74 | //! [here](format::Full#example-output) for sample output. |
75 | //! |
76 | //! * [`format::Compact`]: A variant of the default formatter, optimized for |
77 | //! short line lengths. Fields from the current span context are appended to |
78 | //! the fields of the formatted event. See |
79 | //! [here](format::Compact#example-output) for sample output. |
80 | //! |
81 | //! * [`format::Pretty`]: Emits excessively pretty, multi-line logs, optimized |
82 | //! for human readability. This is primarily intended to be used in local |
83 | //! development and debugging, or for command-line applications, where |
84 | //! automated analysis and compact storage of logs is less of a priority than |
85 | //! readability and visual appeal. See [here](format::Pretty#example-output) |
86 | //! for sample output. |
87 | //! |
88 | //! * [`format::Json`]: Outputs newline-delimited JSON logs. This is intended |
89 | //! for production use with systems where structured logs are consumed as JSON |
90 | //! by analysis and viewing tools. The JSON output is not optimized for human |
91 | //! readability. See [here](format::Json#example-output) for sample output. |
92 | //! |
93 | //! ### Customizing Formatters |
94 | //! |
95 | //! The formatting of log lines for spans and events is controlled by two |
96 | //! traits, [`FormatEvent`] and [`FormatFields`]. The [`FormatEvent`] trait |
97 | //! determines the overall formatting of the log line, such as what information |
98 | //! from the event's metadata and span context is included and in what order. |
99 | //! The [`FormatFields`] trait determines how fields — both the event's |
100 | //! fields and fields on spans — are formatted. |
101 | //! |
102 | //! The [`fmt::format`] module provides several types which implement these traits, |
103 | //! many of which expose additional configuration options to customize their |
104 | //! output. The [`format::Format`] type implements common configuration used by |
105 | //! all the formatters provided in this crate, and can be used as a builder to |
106 | //! set specific formatting settings. For example: |
107 | //! |
108 | //! ``` |
109 | //! use tracing_subscriber::fmt; |
110 | //! |
111 | //! // Configure a custom event formatter |
112 | //! let format = fmt::format() |
113 | //! .with_level(false) // don't include levels in formatted output |
114 | //! .with_target(false) // don't include targets |
115 | //! .with_thread_ids(true) // include the thread ID of the current thread |
116 | //! .with_thread_names(true) // include the name of the current thread |
117 | //! .compact(); // use the `Compact` formatting style. |
118 | //! |
119 | //! // Create a `fmt` subscriber that uses our custom event format, and set it |
120 | //! // as the default. |
121 | //! tracing_subscriber::fmt() |
122 | //! .event_format(format) |
123 | //! .init(); |
124 | //! ``` |
125 | //! |
126 | //! However, if a specific output format is needed, other crates can |
127 | //! also implement [`FormatEvent`] and [`FormatFields`]. See those traits' |
128 | //! documentation for details on how to implement them. |
129 | //! |
130 | //! ## Filters |
131 | //! |
132 | //! If you want to filter the `tracing` `Events` based on environment |
133 | //! variables, you can use the [`EnvFilter`] as follows: |
134 | //! |
135 | //! ```rust |
136 | //! use tracing_subscriber::EnvFilter; |
137 | //! |
138 | //! let filter = EnvFilter::from_default_env(); |
139 | //! ``` |
140 | //! |
141 | //! As mentioned above, the [`EnvFilter`] allows `Span`s and `Event`s to |
142 | //! be filtered at runtime by setting the `RUST_LOG` environment variable. |
143 | //! |
144 | //! You can find the other available [`filter`]s in the documentation. |
145 | //! |
146 | //! ### Using Your Subscriber |
147 | //! |
148 | //! Finally, once you have configured your `Subscriber`, you need to |
149 | //! configure your executable to use it. |
150 | //! |
151 | //! A subscriber can be installed globally using: |
152 | //! ```rust |
153 | //! use tracing; |
154 | //! use tracing_subscriber::FmtSubscriber; |
155 | //! |
156 | //! let subscriber = FmtSubscriber::new(); |
157 | //! |
158 | //! tracing::subscriber::set_global_default(subscriber) |
159 | //! .map_err(|_err| eprintln!("Unable to set global default subscriber" )); |
160 | //! // Note this will only fail if you try to set the global default |
161 | //! // subscriber multiple times |
162 | //! ``` |
163 | //! |
164 | //! ### Composing Layers |
165 | //! |
166 | //! Composing an [`EnvFilter`] `Layer` and a [format `Layer`][super::fmt::Layer]: |
167 | //! |
168 | //! ```rust |
169 | //! use tracing_subscriber::{fmt, EnvFilter}; |
170 | //! use tracing_subscriber::prelude::*; |
171 | //! |
172 | //! let fmt_layer = fmt::layer() |
173 | //! .with_target(false); |
174 | //! let filter_layer = EnvFilter::try_from_default_env() |
175 | //! .or_else(|_| EnvFilter::try_new("info" )) |
176 | //! .unwrap(); |
177 | //! |
178 | //! tracing_subscriber::registry() |
179 | //! .with(filter_layer) |
180 | //! .with(fmt_layer) |
181 | //! .init(); |
182 | //! ``` |
183 | //! |
184 | //! [`EnvFilter`]: super::filter::EnvFilter |
185 | //! [`env_logger`]: https://docs.rs/env_logger/ |
186 | //! [`filter`]: super::filter |
187 | //! [`FmtSubscriber`]: Subscriber |
188 | //! [`Subscriber`]: |
189 | //! https://docs.rs/tracing/latest/tracing/trait.Subscriber.html |
190 | //! [`tracing`]: https://crates.io/crates/tracing |
191 | //! [`fmt::format`]: mod@crate::fmt::format |
192 | use std::{any::TypeId, error::Error, io}; |
193 | use tracing_core::{span, subscriber::Interest, Event, Metadata}; |
194 | |
195 | mod fmt_layer; |
196 | #[cfg_attr (docsrs, doc(cfg(all(feature = "fmt" , feature = "std" ))))] |
197 | pub mod format; |
198 | #[cfg_attr (docsrs, doc(cfg(all(feature = "fmt" , feature = "std" ))))] |
199 | pub mod time; |
200 | #[cfg_attr (docsrs, doc(cfg(all(feature = "fmt" , feature = "std" ))))] |
201 | pub mod writer; |
202 | |
203 | pub use fmt_layer::{FmtContext, FormattedFields, Layer}; |
204 | |
205 | use crate::layer::Layer as _; |
206 | use crate::util::SubscriberInitExt; |
207 | use crate::{ |
208 | filter::LevelFilter, |
209 | layer, |
210 | registry::{LookupSpan, Registry}, |
211 | }; |
212 | |
213 | #[doc (inline)] |
214 | pub use self::{ |
215 | format::{format, FormatEvent, FormatFields}, |
216 | time::time, |
217 | writer::{MakeWriter, TestWriter}, |
218 | }; |
219 | |
220 | /// A `Subscriber` that logs formatted representations of `tracing` events. |
221 | /// |
222 | /// This consists of an inner `Formatter` wrapped in a layer that performs filtering. |
223 | #[cfg_attr (docsrs, doc(cfg(all(feature = "fmt" , feature = "std" ))))] |
224 | #[derive(Debug)] |
225 | pub struct Subscriber< |
226 | N = format::DefaultFields, |
227 | E = format::Format<format::Full>, |
228 | F = LevelFilter, |
229 | W = fn() -> io::Stdout, |
230 | > { |
231 | inner: layer::Layered<F, Formatter<N, E, W>>, |
232 | } |
233 | |
234 | /// A `Subscriber` that logs formatted representations of `tracing` events. |
235 | /// This type only logs formatted events; it does not perform any filtering. |
236 | #[cfg_attr (docsrs, doc(cfg(all(feature = "fmt" , feature = "std" ))))] |
237 | pub type Formatter< |
238 | N = format::DefaultFields, |
239 | E = format::Format<format::Full>, |
240 | W = fn() -> io::Stdout, |
241 | > = layer::Layered<fmt_layer::Layer<Registry, N, E, W>, Registry>; |
242 | |
243 | /// Configures and constructs `Subscriber`s. |
244 | #[cfg_attr (docsrs, doc(cfg(all(feature = "fmt" , feature = "std" ))))] |
245 | #[derive(Debug)] |
246 | #[must_use ] |
247 | pub struct SubscriberBuilder< |
248 | N = format::DefaultFields, |
249 | E = format::Format<format::Full>, |
250 | F = LevelFilter, |
251 | W = fn() -> io::Stdout, |
252 | > { |
253 | filter: F, |
254 | inner: Layer<Registry, N, E, W>, |
255 | } |
256 | |
257 | /// Returns a new [`SubscriberBuilder`] for configuring a [formatting subscriber]. |
258 | /// |
259 | /// This is essentially shorthand for [`SubscriberBuilder::default()]`. |
260 | /// |
261 | /// # Examples |
262 | /// |
263 | /// Using [`init`] to set the default subscriber: |
264 | /// |
265 | /// ```rust |
266 | /// tracing_subscriber::fmt().init(); |
267 | /// ``` |
268 | /// |
269 | /// Configuring the output format: |
270 | /// |
271 | /// ```rust |
272 | /// |
273 | /// tracing_subscriber::fmt() |
274 | /// // Configure formatting settings. |
275 | /// .with_target(false) |
276 | /// .with_timer(tracing_subscriber::fmt::time::uptime()) |
277 | /// .with_level(true) |
278 | /// // Set the subscriber as the default. |
279 | /// .init(); |
280 | /// ``` |
281 | /// |
282 | /// [`try_init`] returns an error if the default subscriber could not be set: |
283 | /// |
284 | /// ```rust |
285 | /// use std::error::Error; |
286 | /// |
287 | /// fn init_subscriber() -> Result<(), Box<dyn Error + Send + Sync + 'static>> { |
288 | /// tracing_subscriber::fmt() |
289 | /// // Configure the subscriber to emit logs in JSON format. |
290 | /// .json() |
291 | /// // Configure the subscriber to flatten event fields in the output JSON objects. |
292 | /// .flatten_event(true) |
293 | /// // Set the subscriber as the default, returning an error if this fails. |
294 | /// .try_init()?; |
295 | /// |
296 | /// Ok(()) |
297 | /// } |
298 | /// ``` |
299 | /// |
300 | /// Rather than setting the subscriber as the default, [`finish`] _returns_ the |
301 | /// constructed subscriber, which may then be passed to other functions: |
302 | /// |
303 | /// ```rust |
304 | /// let subscriber = tracing_subscriber::fmt() |
305 | /// .with_max_level(tracing::Level::DEBUG) |
306 | /// .compact() |
307 | /// .finish(); |
308 | /// |
309 | /// tracing::subscriber::with_default(subscriber, || { |
310 | /// // the subscriber will only be set as the default |
311 | /// // inside this closure... |
312 | /// }) |
313 | /// ``` |
314 | /// |
315 | /// [formatting subscriber]: Subscriber |
316 | /// [`SubscriberBuilder::default()`]: SubscriberBuilder::default |
317 | /// [`init`]: SubscriberBuilder::init() |
318 | /// [`try_init`]: SubscriberBuilder::try_init() |
319 | /// [`finish`]: SubscriberBuilder::finish() |
320 | #[cfg_attr (docsrs, doc(cfg(all(feature = "fmt" , feature = "std" ))))] |
321 | pub fn fmt() -> SubscriberBuilder { |
322 | SubscriberBuilder::default() |
323 | } |
324 | |
325 | /// Returns a new [formatting layer] that can be [composed] with other layers to |
326 | /// construct a [`Subscriber`]. |
327 | /// |
328 | /// This is a shorthand for the equivalent [`Layer::default()`] function. |
329 | /// |
330 | /// [formatting layer]: Layer |
331 | /// [composed]: crate::layer |
332 | /// [`Layer::default()`]: Layer::default |
333 | #[cfg_attr (docsrs, doc(cfg(all(feature = "fmt" , feature = "std" ))))] |
334 | pub fn layer<S>() -> Layer<S> { |
335 | Layer::default() |
336 | } |
337 | |
338 | impl Subscriber { |
339 | /// The maximum [verbosity level] that is enabled by a `Subscriber` by |
340 | /// default. |
341 | /// |
342 | /// This can be overridden with the [`SubscriberBuilder::with_max_level`] method. |
343 | /// |
344 | /// [verbosity level]: tracing_core::Level |
345 | /// [`SubscriberBuilder::with_max_level`]: SubscriberBuilder::with_max_level |
346 | pub const DEFAULT_MAX_LEVEL: LevelFilter = LevelFilter::INFO; |
347 | |
348 | /// Returns a new `SubscriberBuilder` for configuring a format subscriber. |
349 | pub fn builder() -> SubscriberBuilder { |
350 | SubscriberBuilder::default() |
351 | } |
352 | |
353 | /// Returns a new format subscriber with the default configuration. |
354 | pub fn new() -> Self { |
355 | Default::default() |
356 | } |
357 | } |
358 | |
359 | impl Default for Subscriber { |
360 | fn default() -> Self { |
361 | SubscriberBuilder::default().finish() |
362 | } |
363 | } |
364 | |
365 | // === impl Subscriber === |
366 | |
367 | impl<N, E, F, W> tracing_core::Subscriber for Subscriber<N, E, F, W> |
368 | where |
369 | N: for<'writer> FormatFields<'writer> + 'static, |
370 | E: FormatEvent<Registry, N> + 'static, |
371 | F: layer::Layer<Formatter<N, E, W>> + 'static, |
372 | W: for<'writer> MakeWriter<'writer> + 'static, |
373 | layer::Layered<F, Formatter<N, E, W>>: tracing_core::Subscriber, |
374 | fmt_layer::Layer<Registry, N, E, W>: layer::Layer<Registry>, |
375 | { |
376 | #[inline ] |
377 | fn register_callsite(&self, meta: &'static Metadata<'static>) -> Interest { |
378 | self.inner.register_callsite(meta) |
379 | } |
380 | |
381 | #[inline ] |
382 | fn enabled(&self, meta: &Metadata<'_>) -> bool { |
383 | self.inner.enabled(meta) |
384 | } |
385 | |
386 | #[inline ] |
387 | fn new_span(&self, attrs: &span::Attributes<'_>) -> span::Id { |
388 | self.inner.new_span(attrs) |
389 | } |
390 | |
391 | #[inline ] |
392 | fn record(&self, span: &span::Id, values: &span::Record<'_>) { |
393 | self.inner.record(span, values) |
394 | } |
395 | |
396 | #[inline ] |
397 | fn record_follows_from(&self, span: &span::Id, follows: &span::Id) { |
398 | self.inner.record_follows_from(span, follows) |
399 | } |
400 | |
401 | #[inline ] |
402 | fn event_enabled(&self, event: &Event<'_>) -> bool { |
403 | self.inner.event_enabled(event) |
404 | } |
405 | |
406 | #[inline ] |
407 | fn event(&self, event: &Event<'_>) { |
408 | self.inner.event(event); |
409 | } |
410 | |
411 | #[inline ] |
412 | fn enter(&self, id: &span::Id) { |
413 | // TODO: add on_enter hook |
414 | self.inner.enter(id); |
415 | } |
416 | |
417 | #[inline ] |
418 | fn exit(&self, id: &span::Id) { |
419 | self.inner.exit(id); |
420 | } |
421 | |
422 | #[inline ] |
423 | fn current_span(&self) -> span::Current { |
424 | self.inner.current_span() |
425 | } |
426 | |
427 | #[inline ] |
428 | fn clone_span(&self, id: &span::Id) -> span::Id { |
429 | self.inner.clone_span(id) |
430 | } |
431 | |
432 | #[inline ] |
433 | fn try_close(&self, id: span::Id) -> bool { |
434 | self.inner.try_close(id) |
435 | } |
436 | |
437 | #[inline ] |
438 | fn max_level_hint(&self) -> Option<tracing_core::LevelFilter> { |
439 | self.inner.max_level_hint() |
440 | } |
441 | |
442 | unsafe fn downcast_raw(&self, id: TypeId) -> Option<*const ()> { |
443 | if id == TypeId::of::<Self>() { |
444 | Some(self as *const Self as *const ()) |
445 | } else { |
446 | self.inner.downcast_raw(id) |
447 | } |
448 | } |
449 | } |
450 | |
451 | impl<'a, N, E, F, W> LookupSpan<'a> for Subscriber<N, E, F, W> |
452 | where |
453 | layer::Layered<F, Formatter<N, E, W>>: LookupSpan<'a>, |
454 | { |
455 | type Data = <layer::Layered<F, Formatter<N, E, W>> as LookupSpan<'a>>::Data; |
456 | |
457 | fn span_data(&'a self, id: &span::Id) -> Option<Self::Data> { |
458 | self.inner.span_data(id) |
459 | } |
460 | } |
461 | |
462 | // ===== impl SubscriberBuilder ===== |
463 | |
464 | impl Default for SubscriberBuilder { |
465 | fn default() -> Self { |
466 | SubscriberBuilder { |
467 | filter: Subscriber::DEFAULT_MAX_LEVEL, |
468 | inner: Default::default(), |
469 | } |
470 | .log_internal_errors(true) |
471 | } |
472 | } |
473 | |
474 | impl<N, E, F, W> SubscriberBuilder<N, E, F, W> |
475 | where |
476 | N: for<'writer> FormatFields<'writer> + 'static, |
477 | E: FormatEvent<Registry, N> + 'static, |
478 | W: for<'writer> MakeWriter<'writer> + 'static, |
479 | F: layer::Layer<Formatter<N, E, W>> + Send + Sync + 'static, |
480 | fmt_layer::Layer<Registry, N, E, W>: layer::Layer<Registry> + Send + Sync + 'static, |
481 | { |
482 | /// Finish the builder, returning a new `FmtSubscriber`. |
483 | pub fn finish(self) -> Subscriber<N, E, F, W> { |
484 | let subscriber = self.inner.with_subscriber(Registry::default()); |
485 | Subscriber { |
486 | inner: self.filter.with_subscriber(subscriber), |
487 | } |
488 | } |
489 | |
490 | /// Install this Subscriber as the global default if one is |
491 | /// not already set. |
492 | /// |
493 | /// If the `tracing-log` feature is enabled, this will also install |
494 | /// the LogTracer to convert `Log` records into `tracing` `Event`s. |
495 | /// |
496 | /// # Errors |
497 | /// Returns an Error if the initialization was unsuccessful, likely |
498 | /// because a global subscriber was already installed by another |
499 | /// call to `try_init`. |
500 | pub fn try_init(self) -> Result<(), Box<dyn Error + Send + Sync + 'static>> { |
501 | use crate::util::SubscriberInitExt; |
502 | self.finish().try_init()?; |
503 | |
504 | Ok(()) |
505 | } |
506 | |
507 | /// Install this Subscriber as the global default. |
508 | /// |
509 | /// If the `tracing-log` feature is enabled, this will also install |
510 | /// the LogTracer to convert `Log` records into `tracing` `Event`s. |
511 | /// |
512 | /// # Panics |
513 | /// Panics if the initialization was unsuccessful, likely because a |
514 | /// global subscriber was already installed by another call to `try_init`. |
515 | pub fn init(self) { |
516 | self.try_init() |
517 | .expect("Unable to install global subscriber" ) |
518 | } |
519 | } |
520 | |
521 | impl<N, E, F, W> From<SubscriberBuilder<N, E, F, W>> for tracing_core::Dispatch |
522 | where |
523 | N: for<'writer> FormatFields<'writer> + 'static, |
524 | E: FormatEvent<Registry, N> + 'static, |
525 | W: for<'writer> MakeWriter<'writer> + 'static, |
526 | F: layer::Layer<Formatter<N, E, W>> + Send + Sync + 'static, |
527 | fmt_layer::Layer<Registry, N, E, W>: layer::Layer<Registry> + Send + Sync + 'static, |
528 | { |
529 | fn from(builder: SubscriberBuilder<N, E, F, W>) -> tracing_core::Dispatch { |
530 | tracing_core::Dispatch::new(builder.finish()) |
531 | } |
532 | } |
533 | |
534 | impl<N, L, T, F, W> SubscriberBuilder<N, format::Format<L, T>, F, W> |
535 | where |
536 | N: for<'writer> FormatFields<'writer> + 'static, |
537 | { |
538 | /// Use the given [`timer`] for log message timestamps. |
539 | /// |
540 | /// See the [`time` module] for the provided timer implementations. |
541 | /// |
542 | /// Note that using the `"time`"" feature flag enables the |
543 | /// additional time formatters [`UtcTime`] and [`LocalTime`], which use the |
544 | /// [`time` crate] to provide more sophisticated timestamp formatting |
545 | /// options. |
546 | /// |
547 | /// [`timer`]: time::FormatTime |
548 | /// [`time` module]: mod@time |
549 | /// [`UtcTime`]: time::UtcTime |
550 | /// [`LocalTime`]: time::LocalTime |
551 | /// [`time` crate]: https://docs.rs/time/0.3 |
552 | pub fn with_timer<T2>(self, timer: T2) -> SubscriberBuilder<N, format::Format<L, T2>, F, W> { |
553 | SubscriberBuilder { |
554 | filter: self.filter, |
555 | inner: self.inner.with_timer(timer), |
556 | } |
557 | } |
558 | |
559 | /// Do not emit timestamps with log messages. |
560 | pub fn without_time(self) -> SubscriberBuilder<N, format::Format<L, ()>, F, W> { |
561 | SubscriberBuilder { |
562 | filter: self.filter, |
563 | inner: self.inner.without_time(), |
564 | } |
565 | } |
566 | |
567 | /// Configures how synthesized events are emitted at points in the [span |
568 | /// lifecycle][lifecycle]. |
569 | /// |
570 | /// The following options are available: |
571 | /// |
572 | /// - `FmtSpan::NONE`: No events will be synthesized when spans are |
573 | /// created, entered, exited, or closed. Data from spans will still be |
574 | /// included as the context for formatted events. This is the default. |
575 | /// - `FmtSpan::NEW`: An event will be synthesized when spans are created. |
576 | /// - `FmtSpan::ENTER`: An event will be synthesized when spans are entered. |
577 | /// - `FmtSpan::EXIT`: An event will be synthesized when spans are exited. |
578 | /// - `FmtSpan::CLOSE`: An event will be synthesized when a span closes. If |
579 | /// [timestamps are enabled][time] for this formatter, the generated |
580 | /// event will contain fields with the span's _busy time_ (the total |
581 | /// time for which it was entered) and _idle time_ (the total time that |
582 | /// the span existed but was not entered). |
583 | /// - `FmtSpan::ACTIVE`: An event will be synthesized when spans are entered |
584 | /// or exited. |
585 | /// - `FmtSpan::FULL`: Events will be synthesized whenever a span is |
586 | /// created, entered, exited, or closed. If timestamps are enabled, the |
587 | /// close event will contain the span's busy and idle time, as |
588 | /// described above. |
589 | /// |
590 | /// The options can be enabled in any combination. For instance, the following |
591 | /// will synthesize events whenever spans are created and closed: |
592 | /// |
593 | /// ```rust |
594 | /// use tracing_subscriber::fmt::format::FmtSpan; |
595 | /// use tracing_subscriber::fmt; |
596 | /// |
597 | /// let subscriber = fmt() |
598 | /// .with_span_events(FmtSpan::NEW | FmtSpan::CLOSE) |
599 | /// .finish(); |
600 | /// ``` |
601 | /// |
602 | /// Note that the generated events will only be part of the log output by |
603 | /// this formatter; they will not be recorded by other `Subscriber`s or by |
604 | /// `Layer`s added to this subscriber. |
605 | /// |
606 | /// [lifecycle]: https://docs.rs/tracing/latest/tracing/span/index.html#the-span-lifecycle |
607 | /// [time]: SubscriberBuilder::without_time() |
608 | pub fn with_span_events(self, kind: format::FmtSpan) -> Self { |
609 | SubscriberBuilder { |
610 | inner: self.inner.with_span_events(kind), |
611 | ..self |
612 | } |
613 | } |
614 | |
615 | /// Sets whether or not the formatter emits ANSI terminal escape codes |
616 | /// for colors and other text formatting. |
617 | /// |
618 | /// Enabling ANSI escapes (calling `with_ansi(true)`) requires the "ansi" |
619 | /// crate feature flag. Calling `with_ansi(true)` without the "ansi" |
620 | /// feature flag enabled will panic if debug assertions are enabled, or |
621 | /// print a warning otherwise. |
622 | /// |
623 | /// This method itself is still available without the feature flag. This |
624 | /// is to allow ANSI escape codes to be explicitly *disabled* without |
625 | /// having to opt-in to the dependencies required to emit ANSI formatting. |
626 | /// This way, code which constructs a formatter that should never emit |
627 | /// ANSI escape codes can ensure that they are not used, regardless of |
628 | /// whether or not other crates in the dependency graph enable the "ansi" |
629 | /// feature flag. |
630 | #[cfg (feature = "ansi" )] |
631 | #[cfg_attr (docsrs, doc(cfg(feature = "ansi" )))] |
632 | pub fn with_ansi(self, ansi: bool) -> SubscriberBuilder<N, format::Format<L, T>, F, W> { |
633 | SubscriberBuilder { |
634 | inner: self.inner.with_ansi(ansi), |
635 | ..self |
636 | } |
637 | } |
638 | |
639 | /// Sets whether to write errors from [`FormatEvent`] to the writer. |
640 | /// Defaults to true. |
641 | /// |
642 | /// By default, `fmt::Layer` will write any `FormatEvent`-internal errors to |
643 | /// the writer. These errors are unlikely and will only occur if there is a |
644 | /// bug in the `FormatEvent` implementation or its dependencies. |
645 | /// |
646 | /// If writing to the writer fails, the error message is printed to stderr |
647 | /// as a fallback. |
648 | /// |
649 | /// [`FormatEvent`]: crate::fmt::FormatEvent |
650 | pub fn log_internal_errors( |
651 | self, |
652 | log_internal_errors: bool, |
653 | ) -> SubscriberBuilder<N, format::Format<L, T>, F, W> { |
654 | SubscriberBuilder { |
655 | inner: self.inner.log_internal_errors(log_internal_errors), |
656 | ..self |
657 | } |
658 | } |
659 | |
660 | /// Sets whether or not an event's target is displayed. |
661 | pub fn with_target( |
662 | self, |
663 | display_target: bool, |
664 | ) -> SubscriberBuilder<N, format::Format<L, T>, F, W> { |
665 | SubscriberBuilder { |
666 | inner: self.inner.with_target(display_target), |
667 | ..self |
668 | } |
669 | } |
670 | |
671 | /// Sets whether or not an event's [source code file path][file] is |
672 | /// displayed. |
673 | /// |
674 | /// [file]: tracing_core::Metadata::file |
675 | pub fn with_file( |
676 | self, |
677 | display_filename: bool, |
678 | ) -> SubscriberBuilder<N, format::Format<L, T>, F, W> { |
679 | SubscriberBuilder { |
680 | inner: self.inner.with_file(display_filename), |
681 | ..self |
682 | } |
683 | } |
684 | |
685 | /// Sets whether or not an event's [source code line number][line] is |
686 | /// displayed. |
687 | /// |
688 | /// [line]: tracing_core::Metadata::line |
689 | pub fn with_line_number( |
690 | self, |
691 | display_line_number: bool, |
692 | ) -> SubscriberBuilder<N, format::Format<L, T>, F, W> { |
693 | SubscriberBuilder { |
694 | inner: self.inner.with_line_number(display_line_number), |
695 | ..self |
696 | } |
697 | } |
698 | |
699 | /// Sets whether or not an event's level is displayed. |
700 | pub fn with_level( |
701 | self, |
702 | display_level: bool, |
703 | ) -> SubscriberBuilder<N, format::Format<L, T>, F, W> { |
704 | SubscriberBuilder { |
705 | inner: self.inner.with_level(display_level), |
706 | ..self |
707 | } |
708 | } |
709 | |
710 | /// Sets whether or not the [name] of the current thread is displayed |
711 | /// when formatting events. |
712 | /// |
713 | /// [name]: std::thread#naming-threads |
714 | pub fn with_thread_names( |
715 | self, |
716 | display_thread_names: bool, |
717 | ) -> SubscriberBuilder<N, format::Format<L, T>, F, W> { |
718 | SubscriberBuilder { |
719 | inner: self.inner.with_thread_names(display_thread_names), |
720 | ..self |
721 | } |
722 | } |
723 | |
724 | /// Sets whether or not the [thread ID] of the current thread is displayed |
725 | /// when formatting events. |
726 | /// |
727 | /// [thread ID]: std::thread::ThreadId |
728 | pub fn with_thread_ids( |
729 | self, |
730 | display_thread_ids: bool, |
731 | ) -> SubscriberBuilder<N, format::Format<L, T>, F, W> { |
732 | SubscriberBuilder { |
733 | inner: self.inner.with_thread_ids(display_thread_ids), |
734 | ..self |
735 | } |
736 | } |
737 | |
738 | /// Sets the subscriber being built to use a less verbose formatter. |
739 | /// |
740 | /// See [`format::Compact`]. |
741 | pub fn compact(self) -> SubscriberBuilder<N, format::Format<format::Compact, T>, F, W> |
742 | where |
743 | N: for<'writer> FormatFields<'writer> + 'static, |
744 | { |
745 | SubscriberBuilder { |
746 | filter: self.filter, |
747 | inner: self.inner.compact(), |
748 | } |
749 | } |
750 | |
751 | /// Sets the subscriber being built to use an [excessively pretty, human-readable formatter](crate::fmt::format::Pretty). |
752 | #[cfg (feature = "ansi" )] |
753 | #[cfg_attr (docsrs, doc(cfg(feature = "ansi" )))] |
754 | pub fn pretty( |
755 | self, |
756 | ) -> SubscriberBuilder<format::Pretty, format::Format<format::Pretty, T>, F, W> { |
757 | SubscriberBuilder { |
758 | filter: self.filter, |
759 | inner: self.inner.pretty(), |
760 | } |
761 | } |
762 | |
763 | /// Sets the subscriber being built to use a JSON formatter. |
764 | /// |
765 | /// See [`format::Json`] for details. |
766 | #[cfg (feature = "json" )] |
767 | #[cfg_attr (docsrs, doc(cfg(feature = "json" )))] |
768 | pub fn json( |
769 | self, |
770 | ) -> SubscriberBuilder<format::JsonFields, format::Format<format::Json, T>, F, W> |
771 | where |
772 | N: for<'writer> FormatFields<'writer> + 'static, |
773 | { |
774 | SubscriberBuilder { |
775 | filter: self.filter, |
776 | inner: self.inner.json(), |
777 | } |
778 | } |
779 | } |
780 | |
781 | #[cfg (feature = "json" )] |
782 | #[cfg_attr (docsrs, doc(cfg(feature = "json" )))] |
783 | impl<T, F, W> SubscriberBuilder<format::JsonFields, format::Format<format::Json, T>, F, W> { |
784 | /// Sets the json subscriber being built to flatten event metadata. |
785 | /// |
786 | /// See [`format::Json`] for details. |
787 | pub fn flatten_event( |
788 | self, |
789 | flatten_event: bool, |
790 | ) -> SubscriberBuilder<format::JsonFields, format::Format<format::Json, T>, F, W> { |
791 | SubscriberBuilder { |
792 | filter: self.filter, |
793 | inner: self.inner.flatten_event(flatten_event), |
794 | } |
795 | } |
796 | |
797 | /// Sets whether or not the JSON subscriber being built will include the current span |
798 | /// in formatted events. |
799 | /// |
800 | /// See [`format::Json`] for details. |
801 | pub fn with_current_span( |
802 | self, |
803 | display_current_span: bool, |
804 | ) -> SubscriberBuilder<format::JsonFields, format::Format<format::Json, T>, F, W> { |
805 | SubscriberBuilder { |
806 | filter: self.filter, |
807 | inner: self.inner.with_current_span(display_current_span), |
808 | } |
809 | } |
810 | |
811 | /// Sets whether or not the JSON subscriber being built will include a list (from |
812 | /// root to leaf) of all currently entered spans in formatted events. |
813 | /// |
814 | /// See [`format::Json`] for details. |
815 | pub fn with_span_list( |
816 | self, |
817 | display_span_list: bool, |
818 | ) -> SubscriberBuilder<format::JsonFields, format::Format<format::Json, T>, F, W> { |
819 | SubscriberBuilder { |
820 | filter: self.filter, |
821 | inner: self.inner.with_span_list(display_span_list), |
822 | } |
823 | } |
824 | } |
825 | |
826 | #[cfg (feature = "env-filter" )] |
827 | #[cfg_attr (docsrs, doc(cfg(feature = "env-filter" )))] |
828 | impl<N, E, W> SubscriberBuilder<N, E, crate::EnvFilter, W> |
829 | where |
830 | Formatter<N, E, W>: tracing_core::Subscriber + 'static, |
831 | { |
832 | /// Configures the subscriber being built to allow filter reloading at |
833 | /// runtime. |
834 | pub fn with_filter_reloading( |
835 | self, |
836 | ) -> SubscriberBuilder<N, E, crate::reload::Layer<crate::EnvFilter, Formatter<N, E, W>>, W> |
837 | { |
838 | let (filter, _) = crate::reload::Layer::new(self.filter); |
839 | SubscriberBuilder { |
840 | filter, |
841 | inner: self.inner, |
842 | } |
843 | } |
844 | } |
845 | |
846 | #[cfg (feature = "env-filter" )] |
847 | #[cfg_attr (docsrs, doc(cfg(feature = "env-filter" )))] |
848 | impl<N, E, W> SubscriberBuilder<N, E, crate::reload::Layer<crate::EnvFilter, Formatter<N, E, W>>, W> |
849 | where |
850 | Formatter<N, E, W>: tracing_core::Subscriber + 'static, |
851 | { |
852 | /// Returns a `Handle` that may be used to reload the constructed subscriber's |
853 | /// filter. |
854 | pub fn reload_handle(&self) -> crate::reload::Handle<crate::EnvFilter, Formatter<N, E, W>> { |
855 | self.filter.handle() |
856 | } |
857 | } |
858 | |
859 | impl<N, E, F, W> SubscriberBuilder<N, E, F, W> { |
860 | /// Sets the field formatter that the subscriber being built will use to record |
861 | /// fields. |
862 | /// |
863 | /// For example: |
864 | /// ```rust |
865 | /// use tracing_subscriber::fmt::format; |
866 | /// use tracing_subscriber::prelude::*; |
867 | /// |
868 | /// let formatter = |
869 | /// // Construct a custom formatter for `Debug` fields |
870 | /// format::debug_fn(|writer, field, value| write!(writer, "{}: {:?}" , field, value)) |
871 | /// // Use the `tracing_subscriber::MakeFmtExt` trait to wrap the |
872 | /// // formatter so that a delimiter is added between fields. |
873 | /// .delimited(", " ); |
874 | /// |
875 | /// let subscriber = tracing_subscriber::fmt() |
876 | /// .fmt_fields(formatter) |
877 | /// .finish(); |
878 | /// # drop(subscriber) |
879 | /// ``` |
880 | pub fn fmt_fields<N2>(self, fmt_fields: N2) -> SubscriberBuilder<N2, E, F, W> |
881 | where |
882 | N2: for<'writer> FormatFields<'writer> + 'static, |
883 | { |
884 | SubscriberBuilder { |
885 | filter: self.filter, |
886 | inner: self.inner.fmt_fields(fmt_fields), |
887 | } |
888 | } |
889 | |
890 | /// Sets the [`EnvFilter`] that the subscriber will use to determine if |
891 | /// a span or event is enabled. |
892 | /// |
893 | /// Note that this method requires the "env-filter" feature flag to be enabled. |
894 | /// |
895 | /// If a filter was previously set, or a maximum level was set by the |
896 | /// [`with_max_level`] method, that value is replaced by the new filter. |
897 | /// |
898 | /// # Examples |
899 | /// |
900 | /// Setting a filter based on the value of the `RUST_LOG` environment |
901 | /// variable: |
902 | /// ```rust |
903 | /// use tracing_subscriber::{fmt, EnvFilter}; |
904 | /// |
905 | /// fmt() |
906 | /// .with_env_filter(EnvFilter::from_default_env()) |
907 | /// .init(); |
908 | /// ``` |
909 | /// |
910 | /// Setting a filter based on a pre-set filter directive string: |
911 | /// ```rust |
912 | /// use tracing_subscriber::fmt; |
913 | /// |
914 | /// fmt() |
915 | /// .with_env_filter("my_crate=info,my_crate::my_mod=debug,[my_span]=trace") |
916 | /// .init(); |
917 | /// ``` |
918 | /// |
919 | /// Adding additional directives to a filter constructed from an env var: |
920 | /// ```rust |
921 | /// use tracing_subscriber::{fmt, filter::{EnvFilter, LevelFilter}}; |
922 | /// |
923 | /// # fn filter() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> { |
924 | /// let filter = EnvFilter::try_from_env("MY_CUSTOM_FILTER_ENV_VAR")? |
925 | /// // Set the base level when not matched by other directives to WARN. |
926 | /// .add_directive(LevelFilter::WARN.into()) |
927 | /// // Set the max level for `my_crate::my_mod` to DEBUG, overriding |
928 | /// // any directives parsed from the env variable. |
929 | /// .add_directive("my_crate::my_mod=debug".parse()?); |
930 | /// |
931 | /// fmt() |
932 | /// .with_env_filter(filter) |
933 | /// .try_init()?; |
934 | /// # Ok(())} |
935 | /// ``` |
936 | /// [`EnvFilter`]: super::filter::EnvFilter |
937 | /// [`with_max_level`]: SubscriberBuilder::with_max_level() |
938 | #[cfg (feature = "env-filter" )] |
939 | #[cfg_attr (docsrs, doc(cfg(feature = "env-filter" )))] |
940 | pub fn with_env_filter( |
941 | self, |
942 | filter: impl Into<crate::EnvFilter>, |
943 | ) -> SubscriberBuilder<N, E, crate::EnvFilter, W> |
944 | where |
945 | Formatter<N, E, W>: tracing_core::Subscriber + 'static, |
946 | { |
947 | let filter = filter.into(); |
948 | SubscriberBuilder { |
949 | filter, |
950 | inner: self.inner, |
951 | } |
952 | } |
953 | |
954 | /// Sets the maximum [verbosity level] that will be enabled by the |
955 | /// subscriber. |
956 | /// |
957 | /// If the max level has already been set, or a [`EnvFilter`] was added by |
958 | /// [`with_env_filter`], this replaces that configuration with the new |
959 | /// maximum level. |
960 | /// |
961 | /// # Examples |
962 | /// |
963 | /// Enable up to the `DEBUG` verbosity level: |
964 | /// ```rust |
965 | /// use tracing_subscriber::fmt; |
966 | /// use tracing::Level; |
967 | /// |
968 | /// fmt() |
969 | /// .with_max_level(Level::DEBUG) |
970 | /// .init(); |
971 | /// ``` |
972 | /// This subscriber won't record any spans or events! |
973 | /// ```rust |
974 | /// use tracing_subscriber::{fmt, filter::LevelFilter}; |
975 | /// |
976 | /// let subscriber = fmt() |
977 | /// .with_max_level(LevelFilter::OFF) |
978 | /// .finish(); |
979 | /// ``` |
980 | /// [verbosity level]: tracing_core::Level |
981 | /// [`EnvFilter`]: struct@crate::filter::EnvFilter |
982 | /// [`with_env_filter`]: fn@Self::with_env_filter |
983 | pub fn with_max_level( |
984 | self, |
985 | filter: impl Into<LevelFilter>, |
986 | ) -> SubscriberBuilder<N, E, LevelFilter, W> { |
987 | let filter = filter.into(); |
988 | SubscriberBuilder { |
989 | filter, |
990 | inner: self.inner, |
991 | } |
992 | } |
993 | |
994 | /// Sets the [event formatter][`FormatEvent`] that the subscriber being built |
995 | /// will use to format events that occur. |
996 | /// |
997 | /// The event formatter may be any type implementing the [`FormatEvent`] |
998 | /// trait, which is implemented for all functions taking a [`FmtContext`], a |
999 | /// [`Writer`], and an [`Event`]. |
1000 | /// |
1001 | /// # Examples |
1002 | /// |
1003 | /// Setting a type implementing [`FormatEvent`] as the formatter: |
1004 | /// |
1005 | /// ```rust |
1006 | /// use tracing_subscriber::fmt::format; |
1007 | /// |
1008 | /// let subscriber = tracing_subscriber::fmt() |
1009 | /// .event_format(format().compact()) |
1010 | /// .finish(); |
1011 | /// ``` |
1012 | /// |
1013 | /// [`Writer`]: struct@self::format::Writer |
1014 | pub fn event_format<E2>(self, fmt_event: E2) -> SubscriberBuilder<N, E2, F, W> |
1015 | where |
1016 | E2: FormatEvent<Registry, N> + 'static, |
1017 | N: for<'writer> FormatFields<'writer> + 'static, |
1018 | W: for<'writer> MakeWriter<'writer> + 'static, |
1019 | { |
1020 | SubscriberBuilder { |
1021 | filter: self.filter, |
1022 | inner: self.inner.event_format(fmt_event), |
1023 | } |
1024 | } |
1025 | |
1026 | /// Sets the [`MakeWriter`] that the subscriber being built will use to write events. |
1027 | /// |
1028 | /// # Examples |
1029 | /// |
1030 | /// Using `stderr` rather than `stdout`: |
1031 | /// |
1032 | /// ```rust |
1033 | /// use tracing_subscriber::fmt; |
1034 | /// use std::io; |
1035 | /// |
1036 | /// fmt() |
1037 | /// .with_writer(io::stderr) |
1038 | /// .init(); |
1039 | /// ``` |
1040 | pub fn with_writer<W2>(self, make_writer: W2) -> SubscriberBuilder<N, E, F, W2> |
1041 | where |
1042 | W2: for<'writer> MakeWriter<'writer> + 'static, |
1043 | { |
1044 | SubscriberBuilder { |
1045 | filter: self.filter, |
1046 | inner: self.inner.with_writer(make_writer), |
1047 | } |
1048 | } |
1049 | |
1050 | /// Configures the subscriber to support [`libtest`'s output capturing][capturing] when used in |
1051 | /// unit tests. |
1052 | /// |
1053 | /// See [`TestWriter`] for additional details. |
1054 | /// |
1055 | /// # Examples |
1056 | /// |
1057 | /// Using [`TestWriter`] to let `cargo test` capture test output. Note that we do not install it |
1058 | /// globally as it may cause conflicts. |
1059 | /// |
1060 | /// ```rust |
1061 | /// use tracing_subscriber::fmt; |
1062 | /// use tracing::subscriber; |
1063 | /// |
1064 | /// subscriber::set_default( |
1065 | /// fmt() |
1066 | /// .with_test_writer() |
1067 | /// .finish() |
1068 | /// ); |
1069 | /// ``` |
1070 | /// |
1071 | /// [capturing]: |
1072 | /// https://doc.rust-lang.org/book/ch11-02-running-tests.html#showing-function-output |
1073 | /// [`TestWriter`]: writer::TestWriter |
1074 | pub fn with_test_writer(self) -> SubscriberBuilder<N, E, F, TestWriter> { |
1075 | SubscriberBuilder { |
1076 | filter: self.filter, |
1077 | inner: self.inner.with_writer(TestWriter::default()), |
1078 | } |
1079 | } |
1080 | |
1081 | /// Updates the event formatter by applying a function to the existing event formatter. |
1082 | /// |
1083 | /// This sets the event formatter that the subscriber being built will use to record fields. |
1084 | /// |
1085 | /// # Examples |
1086 | /// |
1087 | /// Updating an event formatter: |
1088 | /// |
1089 | /// ```rust |
1090 | /// let subscriber = tracing_subscriber::fmt() |
1091 | /// .map_event_format(|e| e.compact()) |
1092 | /// .finish(); |
1093 | /// ``` |
1094 | pub fn map_event_format<E2>(self, f: impl FnOnce(E) -> E2) -> SubscriberBuilder<N, E2, F, W> |
1095 | where |
1096 | E2: FormatEvent<Registry, N> + 'static, |
1097 | N: for<'writer> FormatFields<'writer> + 'static, |
1098 | W: for<'writer> MakeWriter<'writer> + 'static, |
1099 | { |
1100 | SubscriberBuilder { |
1101 | filter: self.filter, |
1102 | inner: self.inner.map_event_format(f), |
1103 | } |
1104 | } |
1105 | |
1106 | /// Updates the field formatter by applying a function to the existing field formatter. |
1107 | /// |
1108 | /// This sets the field formatter that the subscriber being built will use to record fields. |
1109 | /// |
1110 | /// # Examples |
1111 | /// |
1112 | /// Updating a field formatter: |
1113 | /// |
1114 | /// ```rust |
1115 | /// use tracing_subscriber::field::MakeExt; |
1116 | /// let subscriber = tracing_subscriber::fmt() |
1117 | /// .map_fmt_fields(|f| f.debug_alt()) |
1118 | /// .finish(); |
1119 | /// ``` |
1120 | pub fn map_fmt_fields<N2>(self, f: impl FnOnce(N) -> N2) -> SubscriberBuilder<N2, E, F, W> |
1121 | where |
1122 | N2: for<'writer> FormatFields<'writer> + 'static, |
1123 | { |
1124 | SubscriberBuilder { |
1125 | filter: self.filter, |
1126 | inner: self.inner.map_fmt_fields(f), |
1127 | } |
1128 | } |
1129 | |
1130 | /// Updates the [`MakeWriter`] by applying a function to the existing [`MakeWriter`]. |
1131 | /// |
1132 | /// This sets the [`MakeWriter`] that the subscriber being built will use to write events. |
1133 | /// |
1134 | /// # Examples |
1135 | /// |
1136 | /// Redirect output to stderr if level is <= WARN: |
1137 | /// |
1138 | /// ```rust |
1139 | /// use tracing::Level; |
1140 | /// use tracing_subscriber::fmt::{self, writer::MakeWriterExt}; |
1141 | /// |
1142 | /// let stderr = std::io::stderr.with_max_level(Level::WARN); |
1143 | /// let layer = tracing_subscriber::fmt() |
1144 | /// .map_writer(move |w| stderr.or_else(w)) |
1145 | /// .finish(); |
1146 | /// ``` |
1147 | pub fn map_writer<W2>(self, f: impl FnOnce(W) -> W2) -> SubscriberBuilder<N, E, F, W2> |
1148 | where |
1149 | W2: for<'writer> MakeWriter<'writer> + 'static, |
1150 | { |
1151 | SubscriberBuilder { |
1152 | filter: self.filter, |
1153 | inner: self.inner.map_writer(f), |
1154 | } |
1155 | } |
1156 | } |
1157 | |
1158 | /// Install a global tracing subscriber that listens for events and |
1159 | /// filters based on the value of the [`RUST_LOG` environment variable], |
1160 | /// if one is not already set. |
1161 | /// |
1162 | /// If the `tracing-log` feature is enabled, this will also install |
1163 | /// the [`LogTracer`] to convert `log` records into `tracing` `Event`s. |
1164 | /// |
1165 | /// This is shorthand for |
1166 | /// |
1167 | /// ```rust |
1168 | /// # fn doc() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> { |
1169 | /// tracing_subscriber::fmt().try_init() |
1170 | /// # } |
1171 | /// ``` |
1172 | /// |
1173 | /// |
1174 | /// # Errors |
1175 | /// |
1176 | /// Returns an Error if the initialization was unsuccessful, |
1177 | /// likely because a global subscriber was already installed by another |
1178 | /// call to `try_init`. |
1179 | /// |
1180 | /// [`LogTracer`]: |
1181 | /// https://docs.rs/tracing-log/0.1.0/tracing_log/struct.LogTracer.html |
1182 | /// [`RUST_LOG` environment variable]: crate::filter::EnvFilter::DEFAULT_ENV |
1183 | pub fn try_init() -> Result<(), Box<dyn Error + Send + Sync + 'static>> { |
1184 | let builder = Subscriber::builder(); |
1185 | |
1186 | #[cfg (feature = "env-filter" )] |
1187 | let builder = builder.with_env_filter(crate::EnvFilter::from_default_env()); |
1188 | |
1189 | // If `env-filter` is disabled, remove the default max level filter from the |
1190 | // subscriber; it will be added to the `Targets` filter instead if no filter |
1191 | // is set in `RUST_LOG`. |
1192 | // Replacing the default `LevelFilter` with an `EnvFilter` would imply this, |
1193 | // but we can't replace the builder's filter with a `Targets` filter yet. |
1194 | #[cfg (not(feature = "env-filter" ))] |
1195 | let builder = builder.with_max_level(LevelFilter::TRACE); |
1196 | |
1197 | let subscriber = builder.finish(); |
1198 | #[cfg (not(feature = "env-filter" ))] |
1199 | let subscriber = { |
1200 | use crate::{filter::Targets, layer::SubscriberExt}; |
1201 | use std::{env, str::FromStr}; |
1202 | let targets = match env::var("RUST_LOG" ) { |
1203 | Ok(var) => Targets::from_str(&var) |
1204 | .map_err(|e| { |
1205 | eprintln!("Ignoring `RUST_LOG={:?}`: {}" , var, e); |
1206 | }) |
1207 | .unwrap_or_default(), |
1208 | Err(env::VarError::NotPresent) => { |
1209 | Targets::new().with_default(Subscriber::DEFAULT_MAX_LEVEL) |
1210 | } |
1211 | Err(e) => { |
1212 | eprintln!("Ignoring `RUST_LOG`: {}" , e); |
1213 | Targets::new().with_default(Subscriber::DEFAULT_MAX_LEVEL) |
1214 | } |
1215 | }; |
1216 | subscriber.with(targets) |
1217 | }; |
1218 | |
1219 | subscriber.try_init().map_err(Into::into) |
1220 | } |
1221 | |
1222 | /// Install a global tracing subscriber that listens for events and |
1223 | /// filters based on the value of the [`RUST_LOG` environment variable]. |
1224 | /// |
1225 | /// The configuration of the subscriber initialized by this function |
1226 | /// depends on what [feature flags](crate#feature-flags) are enabled. |
1227 | /// |
1228 | /// If the `tracing-log` feature is enabled, this will also install |
1229 | /// the LogTracer to convert `Log` records into `tracing` `Event`s. |
1230 | /// |
1231 | /// If the `env-filter` feature is enabled, this is shorthand for |
1232 | /// |
1233 | /// ```rust |
1234 | /// # use tracing_subscriber::EnvFilter; |
1235 | /// tracing_subscriber::fmt() |
1236 | /// .with_env_filter(EnvFilter::from_default_env()) |
1237 | /// .init(); |
1238 | /// ``` |
1239 | /// |
1240 | /// # Panics |
1241 | /// Panics if the initialization was unsuccessful, likely because a |
1242 | /// global subscriber was already installed by another call to `try_init`. |
1243 | /// |
1244 | /// [`RUST_LOG` environment variable]: crate::filter::EnvFilter::DEFAULT_ENV |
1245 | pub fn init() { |
1246 | try_init().expect("Unable to install global subscriber" ) |
1247 | } |
1248 | |
1249 | #[cfg (test)] |
1250 | mod test { |
1251 | use crate::{ |
1252 | filter::LevelFilter, |
1253 | fmt::{ |
1254 | format::{self, Format}, |
1255 | time, |
1256 | writer::MakeWriter, |
1257 | Subscriber, |
1258 | }, |
1259 | }; |
1260 | use std::{ |
1261 | io, |
1262 | sync::{Arc, Mutex, MutexGuard, TryLockError}, |
1263 | }; |
1264 | use tracing_core::dispatcher::Dispatch; |
1265 | |
1266 | pub(crate) struct MockWriter { |
1267 | buf: Arc<Mutex<Vec<u8>>>, |
1268 | } |
1269 | |
1270 | impl MockWriter { |
1271 | pub(crate) fn new(buf: Arc<Mutex<Vec<u8>>>) -> Self { |
1272 | Self { buf } |
1273 | } |
1274 | |
1275 | pub(crate) fn map_error<Guard>(err: TryLockError<Guard>) -> io::Error { |
1276 | match err { |
1277 | TryLockError::WouldBlock => io::Error::from(io::ErrorKind::WouldBlock), |
1278 | TryLockError::Poisoned(_) => io::Error::from(io::ErrorKind::Other), |
1279 | } |
1280 | } |
1281 | |
1282 | pub(crate) fn buf(&self) -> io::Result<MutexGuard<'_, Vec<u8>>> { |
1283 | self.buf.try_lock().map_err(Self::map_error) |
1284 | } |
1285 | } |
1286 | |
1287 | impl io::Write for MockWriter { |
1288 | fn write(&mut self, buf: &[u8]) -> io::Result<usize> { |
1289 | self.buf()?.write(buf) |
1290 | } |
1291 | |
1292 | fn flush(&mut self) -> io::Result<()> { |
1293 | self.buf()?.flush() |
1294 | } |
1295 | } |
1296 | |
1297 | #[derive(Clone, Default)] |
1298 | pub(crate) struct MockMakeWriter { |
1299 | buf: Arc<Mutex<Vec<u8>>>, |
1300 | } |
1301 | |
1302 | impl MockMakeWriter { |
1303 | pub(crate) fn new(buf: Arc<Mutex<Vec<u8>>>) -> Self { |
1304 | Self { buf } |
1305 | } |
1306 | |
1307 | // this is currently only used by the JSON formatter tests. if we need |
1308 | // it elsewhere in the future, feel free to remove the `#[cfg]` |
1309 | // attribute! |
1310 | #[cfg (feature = "json" )] |
1311 | pub(crate) fn buf(&self) -> MutexGuard<'_, Vec<u8>> { |
1312 | self.buf.lock().unwrap() |
1313 | } |
1314 | |
1315 | pub(crate) fn get_string(&self) -> String { |
1316 | let mut buf = self.buf.lock().expect("lock shouldn't be poisoned" ); |
1317 | let string = std::str::from_utf8(&buf[..]) |
1318 | .expect("formatter should not have produced invalid utf-8" ) |
1319 | .to_owned(); |
1320 | buf.clear(); |
1321 | string |
1322 | } |
1323 | } |
1324 | |
1325 | impl<'a> MakeWriter<'a> for MockMakeWriter { |
1326 | type Writer = MockWriter; |
1327 | |
1328 | fn make_writer(&'a self) -> Self::Writer { |
1329 | MockWriter::new(self.buf.clone()) |
1330 | } |
1331 | } |
1332 | |
1333 | #[test] |
1334 | fn impls() { |
1335 | let f = Format::default().with_timer(time::Uptime::default()); |
1336 | let subscriber = Subscriber::builder().event_format(f).finish(); |
1337 | let _dispatch = Dispatch::new(subscriber); |
1338 | |
1339 | let f = format::Format::default(); |
1340 | let subscriber = Subscriber::builder().event_format(f).finish(); |
1341 | let _dispatch = Dispatch::new(subscriber); |
1342 | |
1343 | let f = format::Format::default().compact(); |
1344 | let subscriber = Subscriber::builder().event_format(f).finish(); |
1345 | let _dispatch = Dispatch::new(subscriber); |
1346 | } |
1347 | |
1348 | #[test] |
1349 | fn subscriber_downcasts() { |
1350 | let subscriber = Subscriber::builder().finish(); |
1351 | let dispatch = Dispatch::new(subscriber); |
1352 | assert!(dispatch.downcast_ref::<Subscriber>().is_some()); |
1353 | } |
1354 | |
1355 | #[test] |
1356 | fn subscriber_downcasts_to_parts() { |
1357 | let subscriber = Subscriber::new(); |
1358 | let dispatch = Dispatch::new(subscriber); |
1359 | assert!(dispatch.downcast_ref::<format::DefaultFields>().is_some()); |
1360 | assert!(dispatch.downcast_ref::<LevelFilter>().is_some()); |
1361 | assert!(dispatch.downcast_ref::<format::Format>().is_some()) |
1362 | } |
1363 | |
1364 | #[test] |
1365 | fn is_lookup_span() { |
1366 | fn assert_lookup_span<T: for<'a> crate::registry::LookupSpan<'a>>(_: T) {} |
1367 | let subscriber = Subscriber::new(); |
1368 | assert_lookup_span(subscriber) |
1369 | } |
1370 | } |
1371 | |