subscriber: add more ergonomic subscriber configuration APIs

README.md

@@ -49,19 +49,16 @@ The simplest way to use a subscriber is to call the `set_global_default` functio
 
 ```rust
 use tracing::{info, Level};
-use tracing_subscriber::FmtSubscriber;
+use tracing_subscriber;
 
 fn main() {
     // a builder for `FmtSubscriber`.
-    let subscriber = FmtSubscriber::builder()
+    let subscriber = tracing_subscriber::fmt()
         // all spans/events with a level higher than TRACE (e.g, debug, info, warn, etc.)
         // will be written to stdout.
         .with_max_level(Level::TRACE)
-        // completes the builder.
-        .finish();
-
-    tracing::subscriber::set_global_default(subscriber)
-        .expect("setting default subscriber failed");
+        // completes the builder and sets the constructed `Subscriber` as the default.
+        .init();
 
     let number_of_yaks = 3;
     // this creates a new event, outside of any spans.
@@ -88,10 +85,10 @@ In addition, you can locally override the default subscriber. For example:
 
 ```rust
 use tracing::{info, Level};
-use tracing_subscriber::FmtSubscriber;
+use tracing_subscriber;
 
 fn main() {
-    let subscriber = tracing_subscriber::FmtSubscriber::builder()
+    let subscriber = tracing_subscriber::fmt()
         // all spans/events with a level higher than TRACE (e.g, debug, info, warn, etc.)
         // will be written to stdout.
         .with_max_level(Level::TRACE)

examples/README.md

@@ -18,6 +18,10 @@ This directory contains a collection of examples that demonstrate the use of the
     which provides a subscriber implementation that logs traces to the console.
   + `fmt-stderr`: Demonstrates overriding the output stream used by the `fmt`
     subscriber.
+  + `fmt-custom-field`: Demonstrates overriding how the `fmt` subscriber formats
+    fields on spans and events.
+  + `fmt-custom-event`: Demonstrates overriding how the `fmt` subscriber formats
+    events.
   + `subscriber-filter`: Demonstrates the `tracing-subscriber::filter` module,
     which provides a layer which adds configurable filtering to a subscriber
     implementation.

examples/examples/all-levels.rs

@@ -2,7 +2,7 @@ use tracing::Level;
 use tracing_subscriber;
 
 fn main() {
-    tracing_subscriber::FmtSubscriber::builder()
+    tracing_subscriber::fmt()
         // all spans/events with a level higher than TRACE (e.g, info, warn, etc.)
         // will be written to stdout.
         .with_max_level(Level::TRACE)

examples/examples/async_fn.rs

@@ -40,13 +40,12 @@ async fn write(stream: &mut TcpStream) -> io::Result<usize> {
 }
 
 #[tokio::main]
-pub async fn main() -> Result<(), Box<dyn Error>> {
+pub async fn main() -> Result<(), Box<dyn Error + Send + Sync + 'static>> {
     let addr = "127.0.0.1:6142".parse()?;
 
-    let subscriber = tracing_subscriber::fmt::Subscriber::builder()
+    tracing_subscriber::fmt()
         .with_env_filter("async_fn=trace")
-        .finish();
-    tracing::subscriber::set_global_default(subscriber).unwrap();
+        .try_init()?;
 
     // Open a TCP stream to the socket address.
     //

examples/examples/attrs-args.rs

@@ -27,8 +27,7 @@ fn fibonacci_seq(to: u64) -> Vec<u64> {
 }
 
 fn main() {
-    use tracing_subscriber::fmt;
-    let subscriber = fmt::Subscriber::builder()
+    let subscriber = tracing_subscriber::fmt()
         .with_env_filter("attrs_args=trace")
         .finish();
 

examples/examples/attrs-basic.rs

@@ -11,7 +11,7 @@ fn suggest_band() -> String {
 }
 
 fn main() {
-    let subscriber = tracing_subscriber::fmt::Subscriber::builder()
+    let subscriber = tracing_subscriber::fmt()
         .with_env_filter("attrs_basic=trace")
         .finish();
     tracing::subscriber::with_default(subscriber, || {

examples/examples/custom_error.rs

@@ -4,7 +4,7 @@
 use std::error::Error;
 use std::fmt;
 use tracing_error::{ErrorLayer, SpanTrace};
-use tracing_subscriber::{fmt::Layer as FmtLayer, prelude::*, registry::Registry};
+use tracing_subscriber::prelude::*;
 #[derive(Debug)]
 struct FooError {
     message: &'static str,
@@ -50,11 +50,11 @@ fn do_another_thing(
 
 #[tracing::instrument]
 fn main() {
-    let subscriber = Registry::default()
-        .with(FmtLayer::default())
+    tracing_subscriber::registry()
+        .with(tracing_subscriber::fmt::layer())
         // The `ErrorLayer` subscriber layer enables the use of `SpanTrace`.
-        .with(ErrorLayer::default());
-    tracing::subscriber::set_global_default(subscriber).expect("Could not set global default");
+        .with(ErrorLayer::default())
+        .init();
     match do_something("hello world") {
         Ok(result) => println!("did something successfully: {}", result),
         Err(e) => eprintln!("error: {}", e),

examples/examples/echo.rs

@@ -36,13 +36,12 @@ use tracing::{debug, info, info_span, trace_span, warn};
 use tracing_futures::Instrument;
 
 #[tokio::main]
-async fn main() -> Result<(), Box<dyn Error>> {
-    use tracing_subscriber::{EnvFilter, FmtSubscriber};
+async fn main() -> Result<(), Box<dyn Error + Send + Sync + 'static>> {
+    use tracing_subscriber::EnvFilter;
 
-    let subscriber = FmtSubscriber::builder()
+    tracing_subscriber::fmt()
         .with_env_filter(EnvFilter::from_default_env().add_directive("echo=trace".parse()?))
-        .finish();
-    tracing::subscriber::set_global_default(subscriber)?;
+        .try_init()?;
 
     // Allow passing an address to listen on as the first argument of this
     // program, but otherwise we'll just set up our TCP listener on

examples/examples/fmt-custom-event.rs

@@ -0,0 +1,29 @@
+#![deny(rust_2018_idioms)]
+use tracing_subscriber;
+#[path = "fmt/yak_shave.rs"]
+mod yak_shave;
+
+fn main() {
+    use tracing_subscriber::fmt;
+
+    // Configure a custom event formatter
+    let format = fmt::format()
+        .compact() // use an abbreviated format for logging spans
+        .with_level(false) // don't include levels in formatted output
+        .with_target(false); // don't include targets
+
+    // Create a `fmt` subscriber that uses our custom event format, and set it
+    // as the default.
+    tracing_subscriber::fmt().event_format(format).init();
+
+    // Shave some yaks!
+    let number_of_yaks = 3;
+    // this creates a new event, outside of any spans.
+    tracing::info!(number_of_yaks, "preparing to shave yaks");
+
+    let number_shaved = yak_shave::shave_all(number_of_yaks);
+    tracing::info!(
+        all_yaks_shaved = number_shaved == number_of_yaks,
+        "yak shaving completed."
+    );
+}

examples/examples/fmt-custom-field.rs

@@ -0,0 +1,53 @@
+//! This example demonstrates overriding the way `tracing-subscriber`'s
+//! `FmtSubscriber` formats fields on spans and events, using a closure.
+//!
+//! We'll create a custom format that prints key-value pairs separated by
+//! colons rather than equals signs, and separates fields with commas.
+//!
+//! For an event like
+//! ```rust
+//! tracing::info!(hello = "world", answer = 42);
+//! ```
+//!
+//! the default formatter will format the fields like this:
+//! ```not_rust
+//! hello="world" answer=42
+//! ```
+//! while our custom formatter will output
+//! ```not_rust
+//! hello: "world", answer: 42
+//! ```
+#![deny(rust_2018_idioms)]
+use tracing_subscriber;
+
+#[path = "fmt/yak_shave.rs"]
+mod yak_shave;
+
+fn main() {
+    use tracing_subscriber::{fmt::format, prelude::*};
+
+    // Format fields using the provided closure.
+    let format = format::debug_fn(|writer, field, value| {
+        // We'll format the field name and value separated with a colon.
+        write!(writer, "{}: {:?}", field, value)
+    })
+    // Separate each field with a comma.
+    // This method is provided by an extension trait in the
+    // `tracing-subscriber` prelude.
+    .delimited(", ");
+
+    // Create a `fmt` subscriber that uses our custom event format, and set it
+    // as the default.
+    tracing_subscriber::fmt().fmt_fields(format).init();
+
+    // Shave some yaks!
+    let number_of_yaks = 3;
+    // this creates a new event, outside of any spans.
+    tracing::info!(number_of_yaks, "preparing to shave yaks");
+
+    let number_shaved = yak_shave::shave_all(number_of_yaks);
+    tracing::info!(
+        all_yaks_shaved = number_shaved == number_of_yaks,
+        "yak shaving completed."
+    );
+}

examples/examples/fmt-stderr.rs

@@ -3,9 +3,7 @@ use std::io;
 use tracing::error;
 
 fn main() {
-    let subscriber = tracing_subscriber::fmt::Subscriber::builder()
-        .with_writer(io::stderr)
-        .finish();
+    let subscriber = tracing_subscriber::fmt().with_writer(io::stderr).finish();
 
     tracing::subscriber::with_default(subscriber, || {
         error!("This event will be printed to `stderr`.");

examples/examples/fmt.rs

@@ -6,7 +6,7 @@ use tracing_subscriber;
 mod yak_shave;
 
 fn main() {
-    tracing_subscriber::fmt::Subscriber::builder()
+    tracing_subscriber::fmt()
         // all spans/events with a level higher than DEBUG (e.g, info, warn, etc.)
         // will be written to stdout.
         .with_max_level(Level::DEBUG)

examples/examples/futures-proxy-server.rs

@@ -36,11 +36,10 @@ use tracing::{debug, debug_span, info, warn};
 use tracing_attributes::instrument;
 use tracing_futures::Instrument;
 
+type Error = Box<dyn std::error::Error + Send + Sync + 'static>;
+
 #[instrument]
-async fn transfer(
-    mut inbound: TcpStream,
-    proxy_addr: SocketAddr,
-) -> Result<(), Box<dyn std::error::Error>> {
+async fn transfer(mut inbound: TcpStream, proxy_addr: SocketAddr) -> Result<(), Error> {
     let mut outbound = TcpStream::connect(&proxy_addr).await?;
 
     let (mut ri, mut wi) = inbound.split();
@@ -82,7 +81,7 @@ arg_enum! {
 }
 
 #[tokio::main]
-async fn main() -> Result<(), Box<dyn std::error::Error>> {
+async fn main() -> Result<(), Error> {
     let matches = App::new("Proxy Server Example")
         .version("1.0")
         .arg(
@@ -140,25 +139,16 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     Ok(())
 }
 
-fn set_global_default(matches: &ArgMatches<'_>) -> Result<(), Box<dyn std::error::Error>> {
-    use tracing_subscriber::{filter::EnvFilter, FmtSubscriber};
+fn set_global_default(matches: &ArgMatches<'_>) -> Result<(), Error> {
+    let filter = tracing_subscriber::EnvFilter::from_default_env()
+        .add_directive("proxy_server=trace".parse()?);
+    let subscriber = tracing_subscriber::fmt().with_env_filter(filter);
     match value_t!(matches, "log_format", LogFormat).unwrap_or(LogFormat::Plain) {
         LogFormat::Json => {
-            let subscriber = FmtSubscriber::builder()
-                .json()
-                .with_env_filter(
-                    EnvFilter::from_default_env().add_directive("proxy_server=trace".parse()?),
-                )
-                .finish();
-            tracing::subscriber::set_global_default(subscriber)?;
+            subscriber.json().try_init()?;
         }
         LogFormat::Plain => {
-            let subscriber = FmtSubscriber::builder()
-                .with_env_filter(
-                    EnvFilter::from_default_env().add_directive("proxy_server=trace".parse()?),
-                )
-                .finish();
-            tracing::subscriber::set_global_default(subscriber)?;
+            subscriber.try_init()?;
         }
     }
     Ok(())

examples/examples/hyper-echo.rs

@@ -95,7 +95,7 @@ async fn echo(req: Request<Body>) -> Result<Response<Body>, hyper::Error> {
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
     use tracing_log::env_logger::BuilderExt;
 
-    let subscriber = tracing_subscriber::FmtSubscriber::builder()
+    let subscriber = tracing_subscriber::fmt()
         .with_max_level(Level::TRACE)
         .finish();
     let mut builder = env_logger::Builder::new();

examples/examples/instrumented_error.rs

@@ -4,7 +4,7 @@
 use std::error::Error;
 use std::fmt;
 use tracing_error::{prelude::*, ErrorLayer};
-use tracing_subscriber::{prelude::*, registry::Registry};
+use tracing_subscriber::prelude::*;
 
 #[derive(Debug)]
 struct FooError {
@@ -43,11 +43,12 @@ fn do_another_thing(
 
 #[tracing::instrument]
 fn main() {
-    let subscriber = Registry::default()
-        .with(tracing_subscriber::fmt::Layer::default())
+    tracing_subscriber::registry()
+        .with(tracing_subscriber::fmt::layer())
         // The `ErrorLayer` subscriber layer enables the use of `SpanTrace`.
-        .with(ErrorLayer::default());
-    tracing::subscriber::set_global_default(subscriber).expect("Could not set global default");
+        .with(ErrorLayer::default())
+        .init();
+
     match do_something("hello world") {
         Ok(result) => println!("did something successfully: {}", result),
         Err(e) => {

examples/examples/log.rs

@@ -1,5 +1,5 @@
 fn main() {
-    tracing_subscriber::fmt::Subscriber::builder()
+    tracing_subscriber::fmt()
         .with_max_level(tracing::Level::TRACE)
         .init();
 

examples/examples/spawny_thing.rs

@@ -10,6 +10,7 @@
 use tokio;
 
 use futures::future::join_all;
+use std::error::Error;
 use tracing::{debug, info};
 use tracing_attributes::instrument;
 
@@ -37,11 +38,10 @@ async fn subtask(number: usize) -> usize {
 }
 
 #[tokio::main]
-async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let subscriber = tracing_subscriber::fmt::Subscriber::builder()
+async fn main() -> Result<(), Box<dyn Error + Send + Sync + 'static>> {
+    tracing_subscriber::fmt()
         .with_max_level(tracing::Level::DEBUG)
-        .finish();
-    tracing::subscriber::set_global_default(subscriber)?;
+        .try_init()?;
     parent_task(10).await;
     Ok(())
 }

examples/examples/tower-client.rs

@@ -26,10 +26,9 @@ fn req_span<A>(req: &Request<A>) -> tracing::Span {
 
 #[tokio::main]
 async fn main() -> Result<(), Err> {
-    let subscriber = tracing_subscriber::fmt::Subscriber::builder()
+    tracing_subscriber::fmt()
         .with_env_filter("tower=trace")
-        .finish();
-    tracing::subscriber::set_global_default(subscriber)?;
+        .try_init()?;
 
     let mut svc = ServiceBuilder::new()
         .timeout(Duration::from_millis(250))

examples/examples/tower-load.rs

@@ -44,19 +44,18 @@ use tokio::{time, try_join};
 use tower::{Service, ServiceBuilder, ServiceExt};
 use tracing::{self, debug, error, info, span, trace, warn, Level, Span};
 use tracing_futures::Instrument;
-use tracing_subscriber::{filter::EnvFilter, reload::Handle, FmtSubscriber};
+use tracing_subscriber::{filter::EnvFilter, reload::Handle};
 use tracing_tower::{request_span, request_span::make};
 
 type Err = Box<dyn Error + Send + Sync + 'static>;
 
 #[tokio::main]
 async fn main() -> Result<(), Err> {
-    let builder = FmtSubscriber::builder()
+    let builder = tracing_subscriber::fmt()
         .with_env_filter("info,tower_load=debug")
         .with_filter_reloading();
     let handle = builder.reload_handle();
-
-    let _ = tracing::subscriber::set_global_default(builder.finish());
+    builder.try_init()?;
 
     let addr = "[::1]:3000".parse::<SocketAddr>()?;
     let admin_addr = "[::1]:3001".parse::<SocketAddr>()?;