diff options
Diffstat (limited to '')
| -rw-r--r-- | vendor/tracing-subscriber/src/fmt/mod.rs (renamed from vendor/tracing-subscriber-0.3.3/src/fmt/mod.rs) | 392 |
1 files changed, 235 insertions, 157 deletions
diff --git a/vendor/tracing-subscriber-0.3.3/src/fmt/mod.rs b/vendor/tracing-subscriber/src/fmt/mod.rs index d5deb8f0c..025e17504 100644 --- a/vendor/tracing-subscriber-0.3.3/src/fmt/mod.rs +++ b/vendor/tracing-subscriber/src/fmt/mod.rs @@ -13,10 +13,12 @@ //! //! ```toml //! [dependencies] -//! tracing-subscriber = "0.2" +//! tracing-subscriber = "0.3" //! ``` //! -//! *Compiler support: requires rustc 1.39+* +//! *Compiler support: [requires `rustc` 1.49+][msrv]* +//! +//! [msrv]: super#supported-rust-versions //! //! Add the following to your executable to initialize the default subscriber: //! ```rust @@ -68,132 +70,25 @@ //! //! * [`format::Full`]: The default formatter. This emits human-readable, //! single-line logs for each event that occurs, with the current span context -//! displayed before the formatted representation of the event. +//! displayed before the formatted representation of the event. See +//! [here](format::Full#example-output) for sample output. //! -//! For example: -//! <pre><font color="#4E9A06"><b> Finished</b></font> dev [unoptimized + debuginfo] target(s) in 1.59s -//! <font color="#4E9A06"><b> Running</b></font> `target/debug/examples/fmt` -//! <font color="#AAAAAA">Oct 24 12:55:47.814 </font><font color="#4E9A06"> INFO</font> fmt: preparing to shave yaks number_of_yaks=3 -//! <font color="#AAAAAA">Oct 24 12:55:47.814 </font><font color="#4E9A06"> INFO</font> <b>shaving_yaks{</b>yaks=3<b>}</b>: fmt::yak_shave: shaving yaks -//! <font color="#AAAAAA">Oct 24 12:55:47.814 </font><font color="#75507B">TRACE</font> <b>shaving_yaks{</b>yaks=3<b>}</b>:<b>shave{</b>yak=1<b>}</b>: fmt::yak_shave: hello! I'm gonna shave a yak excitement="yay!" -//! <font color="#AAAAAA">Oct 24 12:55:47.814 </font><font color="#75507B">TRACE</font> <b>shaving_yaks{</b>yaks=3<b>}</b>:<b>shave{</b>yak=1<b>}</b>: fmt::yak_shave: yak shaved successfully -//! <font color="#AAAAAA">Oct 24 12:55:47.814 </font><font color="#3465A4">DEBUG</font> <b>shaving_yaks{</b>yaks=3<b>}</b>: yak_events: yak=1 shaved=true -//! <font color="#AAAAAA">Oct 24 12:55:47.814 </font><font color="#75507B">TRACE</font> <b>shaving_yaks{</b>yaks=3<b>}</b>: fmt::yak_shave: yaks_shaved=1 -//! <font color="#AAAAAA">Oct 24 12:55:47.815 </font><font color="#75507B">TRACE</font> <b>shaving_yaks{</b>yaks=3<b>}</b>:<b>shave{</b>yak=2<b>}</b>: fmt::yak_shave: hello! I'm gonna shave a yak excitement="yay!" -//! <font color="#AAAAAA">Oct 24 12:55:47.815 </font><font color="#75507B">TRACE</font> <b>shaving_yaks{</b>yaks=3<b>}</b>:<b>shave{</b>yak=2<b>}</b>: fmt::yak_shave: yak shaved successfully -//! <font color="#AAAAAA">Oct 24 12:55:47.815 </font><font color="#3465A4">DEBUG</font> <b>shaving_yaks{</b>yaks=3<b>}</b>: yak_events: yak=2 shaved=true -//! <font color="#AAAAAA">Oct 24 12:55:47.815 </font><font color="#75507B">TRACE</font> <b>shaving_yaks{</b>yaks=3<b>}</b>: fmt::yak_shave: yaks_shaved=2 -//! <font color="#AAAAAA">Oct 24 12:55:47.815 </font><font color="#75507B">TRACE</font> <b>shaving_yaks{</b>yaks=3<b>}</b>:<b>shave{</b>yak=3<b>}</b>: fmt::yak_shave: hello! I'm gonna shave a yak excitement="yay!" -//! <font color="#AAAAAA">Oct 24 12:55:47.815 </font><font color="#C4A000"> WARN</font> <b>shaving_yaks{</b>yaks=3<b>}</b>:<b>shave{</b>yak=3<b>}</b>: fmt::yak_shave: could not locate yak -//! <font color="#AAAAAA">Oct 24 12:55:47.815 </font><font color="#3465A4">DEBUG</font> <b>shaving_yaks{</b>yaks=3<b>}</b>: yak_events: yak=3 shaved=false -//! <font color="#AAAAAA">Oct 24 12:55:47.815 </font><font color="#CC0000">ERROR</font> <b>shaving_yaks{</b>yaks=3<b>}</b>: fmt::yak_shave: failed to shave yak yak=3 error=missing yak -//! <font color="#AAAAAA">Oct 24 12:55:47.815 </font><font color="#75507B">TRACE</font> <b>shaving_yaks{</b>yaks=3<b>}</b>: fmt::yak_shave: yaks_shaved=2 -//! <font color="#AAAAAA">Oct 24 12:55:47.815 </font><font color="#4E9A06"> INFO</font> fmt: yak shaving completed all_yaks_shaved=false -//! </pre> +//! * [`format::Compact`]: A variant of the default formatter, optimized for +//! short line lengths. Fields from the current span context are appended to +//! the fields of the formatted event. See +//! [here](format::Compact#example-output) for sample output. //! //! * [`format::Pretty`]: Emits excessively pretty, multi-line logs, optimized //! for human readability. This is primarily intended to be used in local //! development and debugging, or for command-line applications, where //! automated analysis and compact storage of logs is less of a priority than -//! readability and visual appeal. -//! -//! For example: -//! <pre><font color="#4E9A06"><b> Finished</b></font> dev [unoptimized + debuginfo] target(s) in 1.61s -//! <font color="#4E9A06"><b> Running</b></font> `target/debug/examples/fmt-pretty` -//! Oct 24 12:57:29.386 <font color="#4E9A06"><b>fmt_pretty</b></font><font color="#4E9A06">: preparing to shave yaks, </font><font color="#4E9A06"><b>number_of_yaks</b></font><font color="#4E9A06">: 3</font> -//! <font color="#AAAAAA"><i>at</i></font> examples/examples/fmt-pretty.rs:16<font color="#AAAAAA"><i> on</i></font> main -//! -//! Oct 24 12:57:29.386 <font color="#4E9A06"><b>fmt_pretty::yak_shave</b></font><font color="#4E9A06">: shaving yaks</font> -//! <font color="#AAAAAA"><i>at</i></font> examples/examples/fmt/yak_shave.rs:38<font color="#AAAAAA"><i> on</i></font> main -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shaving_yaks</b> <font color="#AAAAAA"><i>with</i></font> <b>yaks</b>: 3 -//! -//! Oct 24 12:57:29.387 <font color="#75507B"><b>fmt_pretty::yak_shave</b></font><font color="#75507B">: hello! I'm gonna shave a yak, </font><font color="#75507B"><b>excitement</b></font><font color="#75507B">: "yay!"</font> -//! <font color="#AAAAAA"><i>at</i></font> examples/examples/fmt/yak_shave.rs:14<font color="#AAAAAA"><i> on</i></font> main -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shave</b> <font color="#AAAAAA"><i>with</i></font> <b>yak</b>: 1 -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shaving_yaks</b> <font color="#AAAAAA"><i>with</i></font> <b>yaks</b>: 3 -//! -//! Oct 24 12:57:29.387 <font color="#75507B"><b>fmt_pretty::yak_shave</b></font><font color="#75507B">: yak shaved successfully</font> -//! <font color="#AAAAAA"><i>at</i></font> examples/examples/fmt/yak_shave.rs:22<font color="#AAAAAA"><i> on</i></font> main -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shave</b> <font color="#AAAAAA"><i>with</i></font> <b>yak</b>: 1 -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shaving_yaks</b> <font color="#AAAAAA"><i>with</i></font> <b>yaks</b>: 3 -//! -//! Oct 24 12:57:29.387 <font color="#3465A4"><b>yak_events</b></font><font color="#3465A4">: </font><font color="#3465A4"><b>yak</b></font><font color="#3465A4">: 1, </font><font color="#3465A4"><b>shaved</b></font><font color="#3465A4">: true</font> -//! <font color="#AAAAAA"><i>at</i></font> examples/examples/fmt/yak_shave.rs:43<font color="#AAAAAA"><i> on</i></font> main -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shaving_yaks</b> <font color="#AAAAAA"><i>with</i></font> <b>yaks</b>: 3 -//! -//! Oct 24 12:57:29.387 <font color="#75507B"><b>fmt_pretty::yak_shave</b></font><font color="#75507B">: </font><font color="#75507B"><b>yaks_shaved</b></font><font color="#75507B">: 1</font> -//! <font color="#AAAAAA"><i>at</i></font> examples/examples/fmt/yak_shave.rs:52<font color="#AAAAAA"><i> on</i></font> main -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shaving_yaks</b> <font color="#AAAAAA"><i>with</i></font> <b>yaks</b>: 3 -//! -//! Oct 24 12:57:29.387 <font color="#75507B"><b>fmt_pretty::yak_shave</b></font><font color="#75507B">: hello! I'm gonna shave a yak, </font><font color="#75507B"><b>excitement</b></font><font color="#75507B">: "yay!"</font> -//! <font color="#AAAAAA"><i>at</i></font> examples/examples/fmt/yak_shave.rs:14<font color="#AAAAAA"><i> on</i></font> main -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shave</b> <font color="#AAAAAA"><i>with</i></font> <b>yak</b>: 2 -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shaving_yaks</b> <font color="#AAAAAA"><i>with</i></font> <b>yaks</b>: 3 -//! -//! Oct 24 12:57:29.387 <font color="#75507B"><b>fmt_pretty::yak_shave</b></font><font color="#75507B">: yak shaved successfully</font> -//! <font color="#AAAAAA"><i>at</i></font> examples/examples/fmt/yak_shave.rs:22<font color="#AAAAAA"><i> on</i></font> main -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shave</b> <font color="#AAAAAA"><i>with</i></font> <b>yak</b>: 2 -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shaving_yaks</b> <font color="#AAAAAA"><i>with</i></font> <b>yaks</b>: 3 -//! -//! Oct 24 12:57:29.387 <font color="#3465A4"><b>yak_events</b></font><font color="#3465A4">: </font><font color="#3465A4"><b>yak</b></font><font color="#3465A4">: 2, </font><font color="#3465A4"><b>shaved</b></font><font color="#3465A4">: true</font> -//! <font color="#AAAAAA"><i>at</i></font> examples/examples/fmt/yak_shave.rs:43<font color="#AAAAAA"><i> on</i></font> main -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shaving_yaks</b> <font color="#AAAAAA"><i>with</i></font> <b>yaks</b>: 3 -//! -//! Oct 24 12:57:29.387 <font color="#75507B"><b>fmt_pretty::yak_shave</b></font><font color="#75507B">: </font><font color="#75507B"><b>yaks_shaved</b></font><font color="#75507B">: 2</font> -//! <font color="#AAAAAA"><i>at</i></font> examples/examples/fmt/yak_shave.rs:52<font color="#AAAAAA"><i> on</i></font> main -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shaving_yaks</b> <font color="#AAAAAA"><i>with</i></font> <b>yaks</b>: 3 -//! -//! Oct 24 12:57:29.387 <font color="#75507B"><b>fmt_pretty::yak_shave</b></font><font color="#75507B">: hello! I'm gonna shave a yak, </font><font color="#75507B"><b>excitement</b></font><font color="#75507B">: "yay!"</font> -//! <font color="#AAAAAA"><i>at</i></font> examples/examples/fmt/yak_shave.rs:14<font color="#AAAAAA"><i> on</i></font> main -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shave</b> <font color="#AAAAAA"><i>with</i></font> <b>yak</b>: 3 -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shaving_yaks</b> <font color="#AAAAAA"><i>with</i></font> <b>yaks</b>: 3 -//! -//! Oct 24 12:57:29.387 <font color="#C4A000"><b>fmt_pretty::yak_shave</b></font><font color="#C4A000">: could not locate yak</font> -//! <font color="#AAAAAA"><i>at</i></font> examples/examples/fmt/yak_shave.rs:16<font color="#AAAAAA"><i> on</i></font> main -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shave</b> <font color="#AAAAAA"><i>with</i></font> <b>yak</b>: 3 -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shaving_yaks</b> <font color="#AAAAAA"><i>with</i></font> <b>yaks</b>: 3 -//! -//! Oct 24 12:57:29.387 <font color="#3465A4"><b>yak_events</b></font><font color="#3465A4">: </font><font color="#3465A4"><b>yak</b></font><font color="#3465A4">: 3, </font><font color="#3465A4"><b>shaved</b></font><font color="#3465A4">: false</font> -//! <font color="#AAAAAA"><i>at</i></font> examples/examples/fmt/yak_shave.rs:43<font color="#AAAAAA"><i> on</i></font> main -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shaving_yaks</b> <font color="#AAAAAA"><i>with</i></font> <b>yaks</b>: 3 -//! -//! Oct 24 12:57:29.387 <font color="#CC0000"><b>fmt_pretty::yak_shave</b></font><font color="#CC0000">: failed to shave yak, </font><font color="#CC0000"><b>yak</b></font><font color="#CC0000">: 3, </font><font color="#CC0000"><b>error</b></font><font color="#CC0000">: missing yak</font> -//! <font color="#AAAAAA"><i>at</i></font> examples/examples/fmt/yak_shave.rs:48<font color="#AAAAAA"><i> on</i></font> main -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shaving_yaks</b> <font color="#AAAAAA"><i>with</i></font> <b>yaks</b>: 3 -//! -//! Oct 24 12:57:29.387 <font color="#75507B"><b>fmt_pretty::yak_shave</b></font><font color="#75507B">: </font><font color="#75507B"><b>yaks_shaved</b></font><font color="#75507B">: 2</font> -//! <font color="#AAAAAA"><i>at</i></font> examples/examples/fmt/yak_shave.rs:52<font color="#AAAAAA"><i> on</i></font> main -//! <font color="#AAAAAA"><i>in</i></font> fmt_pretty::yak_shave::<b>shaving_yaks</b> <font color="#AAAAAA"><i>with</i></font> <b>yaks</b>: 3 -//! -//! Oct 24 12:57:29.387 <font color="#4E9A06"><b>fmt_pretty</b></font><font color="#4E9A06">: yak shaving completed, </font><font color="#4E9A06"><b>all_yaks_shaved</b></font><font color="#4E9A06">: false</font> -//! <font color="#AAAAAA"><i>at</i></font> examples/examples/fmt-pretty.rs:19<font color="#AAAAAA"><i> on</i></font> main -//! </pre> +//! readability and visual appeal. See [here](format::Pretty#example-output) +//! for sample output. //! //! * [`format::Json`]: Outputs newline-delimited JSON logs. This is intended //! for production use with systems where structured logs are consumed as JSON -//! by analysis and viewing tools. The JSON output, as seen below, is *not* -//! optimized for human readability. -//! -//! For example: -//! <pre><font color="#4E9A06"><b> Finished</b></font> dev [unoptimized + debuginfo] target(s) in 1.58s -//! <font color="#4E9A06"><b> Running</b></font> `target/debug/examples/fmt-json` -//! {"timestamp":"Oct 24 13:00:00.873","level":"INFO","fields":{"message":"preparing to shave yaks","number_of_yaks":3},"target":"fmt_json"} -//! {"timestamp":"Oct 24 13:00:00.874","level":"INFO","fields":{"message":"shaving yaks"},"target":"fmt_json::yak_shave","spans":[{"yaks":3,"name":"shaving_yaks"}]} -//! {"timestamp":"Oct 24 13:00:00.874","level":"TRACE","fields":{"message":"hello! I'm gonna shave a yak","excitement":"yay!"},"target":"fmt_json::yak_shave","spans":[{"yaks":3,"name":"shaving_yaks"},{"yak":"1","name":"shave"}]} -//! {"timestamp":"Oct 24 13:00:00.874","level":"TRACE","fields":{"message":"yak shaved successfully"},"target":"fmt_json::yak_shave","spans":[{"yaks":3,"name":"shaving_yaks"},{"yak":"1","name":"shave"}]} -//! {"timestamp":"Oct 24 13:00:00.874","level":"DEBUG","fields":{"yak":1,"shaved":true},"target":"yak_events","spans":[{"yaks":3,"name":"shaving_yaks"}]} -//! {"timestamp":"Oct 24 13:00:00.874","level":"TRACE","fields":{"yaks_shaved":1},"target":"fmt_json::yak_shave","spans":[{"yaks":3,"name":"shaving_yaks"}]} -//! {"timestamp":"Oct 24 13:00:00.874","level":"TRACE","fields":{"message":"hello! I'm gonna shave a yak","excitement":"yay!"},"target":"fmt_json::yak_shave","spans":[{"yaks":3,"name":"shaving_yaks"},{"yak":"2","name":"shave"}]} -//! {"timestamp":"Oct 24 13:00:00.874","level":"TRACE","fields":{"message":"yak shaved successfully"},"target":"fmt_json::yak_shave","spans":[{"yaks":3,"name":"shaving_yaks"},{"yak":"2","name":"shave"}]} -//! {"timestamp":"Oct 24 13:00:00.874","level":"DEBUG","fields":{"yak":2,"shaved":true},"target":"yak_events","spans":[{"yaks":3,"name":"shaving_yaks"}]} -//! {"timestamp":"Oct 24 13:00:00.874","level":"TRACE","fields":{"yaks_shaved":2},"target":"fmt_json::yak_shave","spans":[{"yaks":3,"name":"shaving_yaks"}]} -//! {"timestamp":"Oct 24 13:00:00.874","level":"TRACE","fields":{"message":"hello! I'm gonna shave a yak","excitement":"yay!"},"target":"fmt_json::yak_shave","spans":[{"yaks":3,"name":"shaving_yaks"},{"yak":"3","name":"shave"}]} -//! {"timestamp":"Oct 24 13:00:00.875","level":"WARN","fields":{"message":"could not locate yak"},"target":"fmt_json::yak_shave","spans":[{"yaks":3,"name":"shaving_yaks"},{"yak":"3","name":"shave"}]} -//! {"timestamp":"Oct 24 13:00:00.875","level":"DEBUG","fields":{"yak":3,"shaved":false},"target":"yak_events","spans":[{"yaks":3,"name":"shaving_yaks"}]} -//! {"timestamp":"Oct 24 13:00:00.875","level":"ERROR","fields":{"message":"failed to shave yak","yak":3,"error":"missing yak"},"target":"fmt_json::yak_shave","spans":[{"yaks":3,"name":"shaving_yaks"}]} -//! {"timestamp":"Oct 24 13:00:00.875","level":"TRACE","fields":{"yaks_shaved":2},"target":"fmt_json::yak_shave","spans":[{"yaks":3,"name":"shaving_yaks"}]} -//! {"timestamp":"Oct 24 13:00:00.875","level":"INFO","fields":{"message":"yak shaving completed","all_yaks_shaved":false},"target":"fmt_json"} -//! </pre> +//! by analysis and viewing tools. The JSON output is not optimized for human +//! readability. See [here](format::Json#example-output) for sample output. //! //! ### Customizing Formatters //! @@ -221,7 +116,7 @@ //! .with_thread_names(true) // include the name of the current thread //! .compact(); // use the `Compact` formatting style. //! -//! // Create a `fmt` collector that uses our custom event format, and set it +//! // Create a `fmt` subscriber that uses our custom event format, and set it //! // as the default. //! tracing_subscriber::fmt() //! .event_format(format) @@ -268,7 +163,7 @@ //! //! ### Composing Layers //! -//! Composing an [`EnvFilter`] `Layer` and a [format `Layer`](../fmt/struct.Layer.html): +//! Composing an [`EnvFilter`] `Layer` and a [format `Layer`][super::fmt::Layer]: //! //! ```rust //! use tracing_subscriber::{fmt, EnvFilter}; @@ -286,11 +181,10 @@ //! .init(); //! ``` //! -//! [`EnvFilter`]: ../filter/struct.EnvFilter.html +//! [`EnvFilter`]: super::filter::EnvFilter //! [`env_logger`]: https://docs.rs/env_logger/ -//! [`filter`]: ../filter/index.html -//! [`SubscriberBuilder`]: ./struct.SubscriberBuilder.html -//! [`FmtSubscriber`]: ./struct.Subscriber.html +//! [`filter`]: super::filter +//! [`FmtSubscriber`]: Subscriber //! [`Subscriber`]: //! https://docs.rs/tracing/latest/tracing/trait.Subscriber.html //! [`tracing`]: https://crates.io/crates/tracing @@ -309,6 +203,7 @@ pub mod writer; pub use fmt_layer::{FmtContext, FormattedFields, Layer}; use crate::layer::Layer as _; +use crate::util::SubscriberInitExt; use crate::{ filter::LevelFilter, layer, @@ -348,6 +243,7 @@ pub type Formatter< /// Configures and constructs `Subscriber`s. #[cfg_attr(docsrs, doc(cfg(all(feature = "fmt", feature = "std"))))] #[derive(Debug)] +#[must_use] pub struct SubscriberBuilder< N = format::DefaultFields, E = format::Format<format::Full>, @@ -417,7 +313,7 @@ pub struct SubscriberBuilder< /// ``` /// /// [formatting subscriber]: Subscriber -/// [`SubscriberBuilder::default()`]: SubscriberBuilder::default() +/// [`SubscriberBuilder::default()`]: SubscriberBuilder::default /// [`init`]: SubscriberBuilder::init() /// [`try_init`]: SubscriberBuilder::try_init() /// [`finish`]: SubscriberBuilder::finish() @@ -429,10 +325,11 @@ pub fn fmt() -> SubscriberBuilder { /// Returns a new [formatting layer] that can be [composed] with other layers to /// construct a [`Subscriber`]. /// -/// This is a shorthand for the equivalent [`Layer::default`] function. +/// This is a shorthand for the equivalent [`Layer::default()`] function. /// /// [formatting layer]: Layer /// [composed]: crate::layer +/// [`Layer::default()`]: Layer::default #[cfg_attr(docsrs, doc(cfg(all(feature = "fmt", feature = "std"))))] pub fn layer<S>() -> Layer<S> { Layer::default() @@ -444,8 +341,8 @@ impl Subscriber { /// /// This can be overridden with the [`SubscriberBuilder::with_max_level`] method. /// - /// [verbosity level]: https://docs.rs/tracing-core/0.1.5/tracing_core/struct.Level.html - /// [`SubscriberBuilder::with_max_level`]: struct.SubscriberBuilder.html#method.with_max_level + /// [verbosity level]: tracing_core::Level + /// [`SubscriberBuilder::with_max_level`]: SubscriberBuilder::with_max_level pub const DEFAULT_MAX_LEVEL: LevelFilter = LevelFilter::INFO; /// Returns a new `SubscriberBuilder` for configuring a format subscriber. @@ -502,6 +399,11 @@ where } #[inline] + fn event_enabled(&self, event: &Event<'_>) -> bool { + self.inner.event_enabled(event) + } + + #[inline] fn event(&self, event: &Event<'_>) { self.inner.event(event); } @@ -565,6 +467,7 @@ impl Default for SubscriberBuilder { filter: Subscriber::DEFAULT_MAX_LEVEL, inner: Default::default(), } + .log_internal_errors(true) } } @@ -701,7 +604,7 @@ where /// `Layer`s added to this subscriber. /// /// [lifecycle]: https://docs.rs/tracing/latest/tracing/span/index.html#the-span-lifecycle - /// [time]: #method.without_time + /// [time]: SubscriberBuilder::without_time() pub fn with_span_events(self, kind: format::FmtSpan) -> Self { SubscriberBuilder { inner: self.inner.with_span_events(kind), @@ -719,6 +622,27 @@ where } } + /// Sets whether to write errors from [`FormatEvent`] to the writer. + /// Defaults to true. + /// + /// By default, `fmt::Layer` will write any `FormatEvent`-internal errors to + /// the writer. These errors are unlikely and will only occur if there is a + /// bug in the `FormatEvent` implementation or its dependencies. + /// + /// If writing to the writer fails, the error message is printed to stderr + /// as a fallback. + /// + /// [`FormatEvent`]: crate::fmt::FormatEvent + pub fn log_internal_errors( + self, + log_internal_errors: bool, + ) -> SubscriberBuilder<N, format::Format<L, T>, F, W> { + SubscriberBuilder { + inner: self.inner.log_internal_errors(log_internal_errors), + ..self + } + } + /// Sets whether or not an event's target is displayed. pub fn with_target( self, @@ -730,6 +654,34 @@ where } } + /// Sets whether or not an event's [source code file path][file] is + /// displayed. + /// + /// [file]: tracing_core::Metadata::file + pub fn with_file( + self, + display_filename: bool, + ) -> SubscriberBuilder<N, format::Format<L, T>, F, W> { + SubscriberBuilder { + inner: self.inner.with_file(display_filename), + ..self + } + } + + /// Sets whether or not an event's [source code line number][line] is + /// displayed. + /// + /// [line]: tracing_core::Metadata::line + pub fn with_line_number( + self, + display_line_number: bool, + ) -> SubscriberBuilder<N, format::Format<L, T>, F, W> { + SubscriberBuilder { + inner: self.inner.with_line_number(display_line_number), + ..self + } + } + /// Sets whether or not an event's level is displayed. pub fn with_level( self, @@ -742,9 +694,9 @@ where } /// Sets whether or not the [name] of the current thread is displayed - /// when formatting events + /// when formatting events. /// - /// [name]: https://doc.rust-lang.org/stable/std/thread/index.html#naming-threads + /// [name]: std::thread#naming-threads pub fn with_thread_names( self, display_thread_names: bool, @@ -756,9 +708,9 @@ where } /// Sets whether or not the [thread ID] of the current thread is displayed - /// when formatting events + /// when formatting events. /// - /// [thread ID]: https://doc.rust-lang.org/stable/std/thread/struct.ThreadId.html + /// [thread ID]: std::thread::ThreadId pub fn with_thread_ids( self, display_thread_ids: bool, @@ -796,7 +748,7 @@ where /// Sets the subscriber being built to use a JSON formatter. /// - /// See [`format::Json`](../fmt/format/struct.Json.html) + /// See [`format::Json`][super::fmt::format::Json] #[cfg(feature = "json")] #[cfg_attr(docsrs, doc(cfg(feature = "json")))] pub fn json( @@ -817,7 +769,7 @@ where impl<T, F, W> SubscriberBuilder<format::JsonFields, format::Format<format::Json, T>, F, W> { /// Sets the json subscriber being built to flatten event metadata. /// - /// See [`format::Json`](../fmt/format/struct.Json.html) + /// See [`format::Json`][super::fmt::format::Json] pub fn flatten_event( self, flatten_event: bool, @@ -831,7 +783,7 @@ impl<T, F, W> SubscriberBuilder<format::JsonFields, format::Format<format::Json, /// Sets whether or not the JSON subscriber being built will include the current span /// in formatted events. /// - /// See [`format::Json`](../fmt/format/struct.Json.html) + /// See [`format::Json`][super::fmt::format::Json] pub fn with_current_span( self, display_current_span: bool, @@ -845,7 +797,7 @@ impl<T, F, W> SubscriberBuilder<format::JsonFields, format::Format<format::Json, /// Sets whether or not the JSON subscriber being built will include a list (from /// root to leaf) of all currently entered spans in formatted events. /// - /// See [`format::Json`](../fmt/format/struct.Json.html) + /// See [`format::Json`][super::fmt::format::Json] pub fn with_span_list( self, display_span_list: bool, @@ -891,7 +843,7 @@ where } impl<N, E, F, W> SubscriberBuilder<N, E, F, W> { - /// Sets the Visitor that the subscriber being built will use to record + /// Sets the field formatter that the subscriber being built will use to record /// fields. /// /// For example: @@ -967,8 +919,8 @@ impl<N, E, F, W> SubscriberBuilder<N, E, F, W> { /// .try_init()?; /// # Ok(())} /// ``` - /// [`EnvFilter`]: ../filter/struct.EnvFilter.html - /// [`with_max_level`]: #method.with_max_level + /// [`EnvFilter`]: super::filter::EnvFilter + /// [`with_max_level`]: SubscriberBuilder::with_max_level() #[cfg(feature = "env-filter")] #[cfg_attr(docsrs, doc(cfg(feature = "env-filter")))] pub fn with_env_filter( @@ -989,7 +941,7 @@ impl<N, E, F, W> SubscriberBuilder<N, E, F, W> { /// subscriber. /// /// If the max level has already been set, or a [`EnvFilter`] was added by - /// [`with_filter`], this replaces that configuration with the new + /// [`with_env_filter`], this replaces that configuration with the new /// maximum level. /// /// # Examples @@ -1011,9 +963,9 @@ impl<N, E, F, W> SubscriberBuilder<N, E, F, W> { /// .with_max_level(LevelFilter::OFF) /// .finish(); /// ``` - /// [verbosity level]: https://docs.rs/tracing-core/0.1.5/tracing_core/struct.Level.html - /// [`EnvFilter`]: ../filter/struct.EnvFilter.html - /// [`with_filter`]: #method.with_filter + /// [verbosity level]: tracing_core::Level + /// [`EnvFilter`]: struct@crate::filter::EnvFilter + /// [`with_env_filter`]: fn@Self::with_env_filter pub fn with_max_level( self, filter: impl Into<LevelFilter>, @@ -1025,8 +977,26 @@ impl<N, E, F, W> SubscriberBuilder<N, E, F, W> { } } - /// Sets the function that the subscriber being built should use to format - /// events that occur. + /// Sets the [event formatter][`FormatEvent`] that the subscriber being built + /// will use to format events that occur. + /// + /// The event formatter may be any type implementing the [`FormatEvent`] + /// trait, which is implemented for all functions taking a [`FmtContext`], a + /// [`Writer`], and an [`Event`]. + /// + /// # Examples + /// + /// Setting a type implementing [`FormatEvent`] as the formatter: + /// + /// ```rust + /// use tracing_subscriber::fmt::format; + /// + /// let subscriber = tracing_subscriber::fmt() + /// .event_format(format().compact()) + /// .finish(); + /// ``` + /// + /// [`Writer`]: struct@self::format::Writer pub fn event_format<E2>(self, fmt_event: E2) -> SubscriberBuilder<N, E2, F, W> where E2: FormatEvent<Registry, N> + 'static, @@ -1053,8 +1023,6 @@ impl<N, E, F, W> SubscriberBuilder<N, E, F, W> { /// .with_writer(io::stderr) /// .init(); /// ``` - /// - /// [`MakeWriter`]: trait.MakeWriter.html pub fn with_writer<W2>(self, make_writer: W2) -> SubscriberBuilder<N, E, F, W2> where W2: for<'writer> MakeWriter<'writer> + 'static, @@ -1088,13 +1056,89 @@ impl<N, E, F, W> SubscriberBuilder<N, E, F, W> { /// /// [capturing]: /// https://doc.rust-lang.org/book/ch11-02-running-tests.html#showing-function-output - /// [`TestWriter`]: writer/struct.TestWriter.html + /// [`TestWriter`]: writer::TestWriter pub fn with_test_writer(self) -> SubscriberBuilder<N, E, F, TestWriter> { SubscriberBuilder { filter: self.filter, inner: self.inner.with_writer(TestWriter::default()), } } + + /// Updates the event formatter by applying a function to the existing event formatter. + /// + /// This sets the event formatter that the subscriber being built will use to record fields. + /// + /// # Examples + /// + /// Updating an event formatter: + /// + /// ```rust + /// let subscriber = tracing_subscriber::fmt() + /// .map_event_format(|e| e.compact()) + /// .finish(); + /// ``` + pub fn map_event_format<E2>(self, f: impl FnOnce(E) -> E2) -> SubscriberBuilder<N, E2, F, W> + where + E2: FormatEvent<Registry, N> + 'static, + N: for<'writer> FormatFields<'writer> + 'static, + W: for<'writer> MakeWriter<'writer> + 'static, + { + SubscriberBuilder { + filter: self.filter, + inner: self.inner.map_event_format(f), + } + } + + /// Updates the field formatter by applying a function to the existing field formatter. + /// + /// This sets the field formatter that the subscriber being built will use to record fields. + /// + /// # Examples + /// + /// Updating a field formatter: + /// + /// ```rust + /// use tracing_subscriber::field::MakeExt; + /// let subscriber = tracing_subscriber::fmt() + /// .map_fmt_fields(|f| f.debug_alt()) + /// .finish(); + /// ``` + pub fn map_fmt_fields<N2>(self, f: impl FnOnce(N) -> N2) -> SubscriberBuilder<N2, E, F, W> + where + N2: for<'writer> FormatFields<'writer> + 'static, + { + SubscriberBuilder { + filter: self.filter, + inner: self.inner.map_fmt_fields(f), + } + } + + /// Updates the [`MakeWriter`] by applying a function to the existing [`MakeWriter`]. + /// + /// This sets the [`MakeWriter`] that the subscriber being built will use to write events. + /// + /// # Examples + /// + /// Redirect output to stderr if level is <= WARN: + /// + /// ```rust + /// use tracing::Level; + /// use tracing_subscriber::fmt::{self, writer::MakeWriterExt}; + /// + /// let stderr = std::io::stderr.with_max_level(Level::WARN); + /// let layer = tracing_subscriber::fmt() + /// .map_writer(move |w| stderr.or_else(w)) + /// .finish(); + /// ``` + pub fn map_writer<W2>(self, f: impl FnOnce(W) -> W2) -> SubscriberBuilder<N, E, F, W2> + where + W2: for<'writer> MakeWriter<'writer> + 'static, + { + SubscriberBuilder { + filter: self.filter, + inner: self.inner.map_writer(f), + } + } } /// Install a global tracing subscriber that listens for events and @@ -1121,35 +1165,69 @@ impl<N, E, F, W> SubscriberBuilder<N, E, F, W> { /// /// [`LogTracer`]: /// https://docs.rs/tracing-log/0.1.0/tracing_log/struct.LogTracer.html -/// [`RUST_LOG` environment variable]: -/// ../filter/struct.EnvFilter.html#associatedconstant.DEFAULT_ENV +/// [`RUST_LOG` environment variable]: crate::filter::EnvFilter::DEFAULT_ENV pub fn try_init() -> Result<(), Box<dyn Error + Send + Sync + 'static>> { let builder = Subscriber::builder(); #[cfg(feature = "env-filter")] let builder = builder.with_env_filter(crate::EnvFilter::from_default_env()); - builder.try_init() + // If `env-filter` is disabled, remove the default max level filter from the + // subscriber; it will be added to the `Targets` filter instead if no filter + // is set in `RUST_LOG`. + // Replacing the default `LevelFilter` with an `EnvFilter` would imply this, + // but we can't replace the builder's filter with a `Targets` filter yet. + #[cfg(not(feature = "env-filter"))] + let builder = builder.with_max_level(LevelFilter::TRACE); + + let subscriber = builder.finish(); + #[cfg(not(feature = "env-filter"))] + let subscriber = { + use crate::{filter::Targets, layer::SubscriberExt}; + use std::{env, str::FromStr}; + let targets = match env::var("RUST_LOG") { + Ok(var) => Targets::from_str(&var) + .map_err(|e| { + eprintln!("Ignoring `RUST_LOG={:?}`: {}", var, e); + }) + .unwrap_or_default(), + Err(env::VarError::NotPresent) => { + Targets::new().with_default(Subscriber::DEFAULT_MAX_LEVEL) + } + Err(e) => { + eprintln!("Ignoring `RUST_LOG`: {}", e); + Targets::new().with_default(Subscriber::DEFAULT_MAX_LEVEL) + } + }; + subscriber.with(targets) + }; + + subscriber.try_init().map_err(Into::into) } /// Install a global tracing subscriber that listens for events and /// filters based on the value of the [`RUST_LOG` environment variable]. /// +/// The configuration of the subscriber initialized by this function +/// depends on what [feature flags](crate#feature-flags) are enabled. +/// /// If the `tracing-log` feature is enabled, this will also install /// the LogTracer to convert `Log` records into `tracing` `Event`s. /// -/// This is shorthand for +/// If the `env-filter` feature is enabled, this is shorthand for /// /// ```rust -/// tracing_subscriber::fmt().init() +/// # use tracing_subscriber::EnvFilter; +/// tracing_subscriber::fmt() +/// .with_env_filter(EnvFilter::from_default_env()) +/// .init(); /// ``` /// /// # Panics /// Panics if the initialization was unsuccessful, likely because a /// global subscriber was already installed by another call to `try_init`. /// -/// [`RUST_LOG` environment variable]: -/// ../filter/struct.EnvFilter.html#associatedconstant.DEFAULT_ENV +/// [`RUST_LOG` environment variable]: crate::filter::EnvFilter::DEFAULT_ENV pub fn init() { try_init().expect("Unable to install global subscriber") } |