From d556a8d10e0f9d98971ba82e06e221777b478274 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20Ml=C3=A1dek?= Date: Wed, 19 Jun 2024 00:46:29 +0200 Subject: [PATCH] fix doctests --- src/fmt/builder.rs | 58 ++++++++++++++++++++++++++++++++++------------ src/fmt/layer.rs | 50 ++++++++++++++++++--------------------- src/fmt/mod.rs | 1 + src/layer/mod.rs | 52 +++++++++++++++-------------------------- src/lib.rs | 6 ++++- 5 files changed, 90 insertions(+), 77 deletions(-) diff --git a/src/fmt/builder.rs b/src/fmt/builder.rs index bf62073..aff54d4 100644 --- a/src/fmt/builder.rs +++ b/src/fmt/builder.rs @@ -41,7 +41,7 @@ use crate::layer::JsonLayer; /// Using [`init`] to set the default subscriber: /// /// ```rust -/// json_subscriber::builder::SubscriberBuilder::default().init(); +/// json_subscriber::fmt::SubscriberBuilder::default().init(); /// ``` /// /// Configuring the output format: @@ -80,7 +80,6 @@ use crate::layer::JsonLayer; /// ```rust /// let subscriber = json_subscriber::fmt() /// .with_max_level(tracing::Level::DEBUG) -/// .compact() /// .finish(); /// /// tracing::subscriber::with_default(subscriber, || { @@ -301,7 +300,7 @@ impl SubscriberBuilder { /// ``` /// use tracing_subscriber::{fmt::writer::EitherWriter, reload}; /// # fn main() { - /// let subscriber = json_subscriber::fmt::subscriber() + /// let subscriber = json_subscriber::fmt() /// .with_writer:: EitherWriter<_, _>>>(Box::new(|| EitherWriter::A(std::io::stderr()))); /// let (subscriber, reload_handle) = reload::Layer::new(subscriber); /// # let subscriber: reload::Layer<_, tracing_subscriber::Registry> = subscriber; @@ -327,10 +326,7 @@ impl SubscriberBuilder { /// Using [`TestWriter`] to let `cargo test` capture test output: /// /// ```rust - /// use std::io; - /// use json_subscriber::fmt; - /// - /// let fmt_subscriber = fmt::subscriber() + /// let fmt_subscriber = json_subscriber::fmt::fmt() /// .with_test_writer(); /// ``` /// [capturing]: @@ -378,11 +374,10 @@ impl SubscriberBuilder { /// /// ```rust /// use tracing::Level; - /// use json_subscriber::fmt; /// use tracing_subscriber::fmt::writer::MakeWriterExt; /// /// let stderr = std::io::stderr.with_max_level(Level::WARN); - /// let subscriber = fmt::subscriber() + /// let subscriber = json_subscriber::fmt::fmt() /// .map_writer(move |w| stderr.or_else(w)); /// ``` pub fn map_writer(self, f: impl FnOnce(W) -> W2) -> SubscriberBuilder @@ -747,11 +742,11 @@ impl SubscriberBuilder { /// /// For example: /// - /// ``` + /// ```rust + /// # use tracing_subscriber::prelude::*; /// use tracing::Level; - /// use tracing_subscriber::util::SubscriberInitExt; /// - /// let builder = tracing_subscriber::fmt() + /// let builder = json_subscriber::fmt() /// // Set a max level filter on the collector /// .with_max_level(Level::INFO) /// .with_filter_reloading(); @@ -775,7 +770,9 @@ impl SubscriberBuilder { /// ``` /// /// [`reload_handle`]: Self::reload_handle - pub fn with_filter_reloading(self) -> SubscriberBuilder> { + #[cfg(feature = "env-filter")] + #[cfg_attr(docsrs, doc(cfg(feature = "env-filter")))] + pub fn with_filter_reloading(self) -> SubscriberBuilder> { let (filter, _) = reload::Layer::new(self.filter); SubscriberBuilder { make_writer: self.make_writer, @@ -798,10 +795,10 @@ impl SubscriberBuilder { } } -impl SubscriberBuilder> { +impl SubscriberBuilder> { /// Returns a `Handle` that may be used to reload the constructed collector's /// filter. - pub fn reload_handle(&self) -> reload::Handle { + pub fn reload_handle(&self) -> reload::Handle { self.filter.handle() } } @@ -1132,4 +1129,35 @@ mod tests { let subscriber = SubscriberBuilder::default().finish(); assert_lookup_span(subscriber) } + + #[test] + #[cfg(feature = "env-filter")] + fn reload_filter_works() { + use tracing::Level; + use tracing_subscriber::util::SubscriberInitExt; + + let builder = SubscriberBuilder::default() + // Set a max level filter on the collector + .with_max_level(Level::INFO) + .with_filter_reloading(); + + // Get a handle for modifying the collector's max level filter. + let handle = builder.reload_handle(); + + // Finish building the collector, and set it as the default. + builder.finish().init(); + + // Currently, the max level is INFO, so this event will be disabled. + tracing::debug!("this is not recorded!"); + + // Use the handle to set a new max level filter. + // (this returns an error if the collector has been dropped, which shouldn't + // happen in this example.) + handle + .reload(Level::DEBUG) + .expect("the collector should still exist"); + + // Now, the max level is INFO, so this event will be recorded. + tracing::debug!("this is recorded!"); + } } diff --git a/src/fmt/layer.rs b/src/fmt/layer.rs index 745120f..45e1b44 100644 --- a/src/fmt/layer.rs +++ b/src/fmt/layer.rs @@ -187,14 +187,10 @@ where /// Using `stderr` rather than `stdout`: /// /// ```rust - /// use std::io; - /// use tracing_subscriber::fmt; - /// - /// let fmt_subscriber = fmt::subscriber() - /// .with_writer(io::stderr); - /// # // this is necessary for type inference. - /// # use tracing_subscriber::Subscribe as _; - /// # let _ = fmt_subscriber.with_collector(tracing_subscriber::registry::Registry::default()); + /// # use tracing_subscriber::prelude::*; + /// let layer = json_subscriber::fmt::layer() + /// .with_writer(std::io::stderr); + /// # tracing_subscriber::registry().with(layer); /// ``` /// /// [`MakeWriter`]: MakeWriter @@ -217,15 +213,13 @@ where /// Redirect output to stderr if level is <= WARN: /// /// ```rust - /// use tracing::Level; - /// use tracing_subscriber::fmt::{self, writer::MakeWriterExt}; + /// # use tracing_subscriber::prelude::*; + /// use tracing_subscriber::fmt::writer::MakeWriterExt; /// - /// let stderr = std::io::stderr.with_max_level(Level::WARN); - /// let subscriber = fmt::subscriber() + /// let stderr = std::io::stderr.with_max_level(tracing::Level::WARN); + /// let layer = json_subscriber::fmt::layer() /// .map_writer(move |w| stderr.or_else(w)); - /// # // this is necessary for type inference. - /// # use tracing_subscriber::Subscribe as _; - /// # let _ = subscriber.with_collector(tracing_subscriber::registry::Registry::default()); + /// # tracing_subscriber::registry().with(layer); /// ``` pub fn map_writer(self, f: impl FnOnce(W) -> W2) -> Layer where @@ -246,14 +240,12 @@ where /// Using [`TestWriter`] to let `cargo test` capture test output: /// /// ```rust - /// use std::io; - /// use tracing_subscriber::fmt; + /// # use tracing_subscriber::prelude::*; + /// use tracing_subscriber::fmt::writer::MakeWriterExt; /// - /// let fmt_subscriber = fmt::subscriber() + /// let layer = json_subscriber::fmt::layer() /// .with_test_writer(); - /// # // this is necessary for type inference. - /// # use tracing_subscriber::Subscribe as _; - /// # let _ = fmt_subscriber.with_collector(tracing_subscriber::registry::Registry::default()); + /// # tracing_subscriber::registry().with(layer); /// ``` /// [capturing]: /// https://doc.rust-lang.org/book/ch11-02-running-tests.html#showing-function-output @@ -284,12 +276,11 @@ where /// # std::io::stdout /// # } /// # fn main() { - /// let subscriber = fmt::subscriber().with_writer(non_blocking(std::io::stderr())); - /// let (subscriber, reload_handle) = reload::JsonLayer::new(subscriber); - /// # - /// # // specifying the Registry type is required - /// # let _: &reload::Handle = &reload_handle; - /// # + /// let layer = json_subscriber::fmt::layer().with_writer(non_blocking(std::io::stderr())); + /// let (layer, reload_handle) = reload::Layer::new(layer); + /// + /// tracing_subscriber::registry().with(layer).init(); + /// /// info!("This will be logged to stderr"); /// reload_handle.modify(|subscriber| *subscriber.writer_mut() = non_blocking(std::io::stdout())); /// info!("This will be logged to stdout"); @@ -308,7 +299,8 @@ where /// /// # Examples /// ```rust - /// let mut layer = tracing_json::layer(); + /// # use tracing_subscriber::prelude::*; + /// let mut layer = json_subscriber::layer(); /// let mut inner = layer.inner_layer_mut(); /// /// inner.add_static_field( @@ -317,6 +309,8 @@ where /// "hostname": get_hostname(), /// }), /// ); + /// # tracing_subscriber::registry().with(layer); + /// # fn get_hostname() -> &'static str { "localhost" } /// ``` /// /// [`reload::Handle::modify`]: tracing_subscriber::reload::Handle::modify diff --git a/src/fmt/mod.rs b/src/fmt/mod.rs index 85483bf..3b85e67 100644 --- a/src/fmt/mod.rs +++ b/src/fmt/mod.rs @@ -108,6 +108,7 @@ impl Subscriber { /// # Examples /// /// ```rust + /// # use json_subscriber::fmt::Subscriber; /// let subscriber = Subscriber::builder() /// .with_max_level(tracing::Level::INFO) /// .with_target(false) diff --git a/src/layer/mod.rs b/src/layer/mod.rs index a0119c8..66998e8 100644 --- a/src/layer/mod.rs +++ b/src/layer/mod.rs @@ -223,14 +223,10 @@ where /// Using `stderr` rather than `stdout`: /// /// ```rust - /// use std::io; - /// use tracing_subscriber::fmt; - /// - /// let fmt_subscriber = fmt::subscriber() - /// .with_writer(io::stderr); - /// # // this is necessary for type inference. - /// # use tracing_subscriber::Subscribe as _; - /// # let _ = fmt_subscriber.with_collector(tracing_subscriber::registry::Registry::default()); + /// # use tracing_subscriber::prelude::*; + /// let layer = json_subscriber::JsonLayer::stdout() + /// .with_writer(std::io::stderr); + /// # tracing_subscriber::registry().with(layer); /// ``` /// /// [`MakeWriter`]: MakeWriter @@ -267,12 +263,11 @@ where /// # std::io::stdout /// # } /// # fn main() { - /// let subscriber = fmt::subscriber().with_writer(non_blocking(std::io::stderr())); - /// let (subscriber, reload_handle) = reload::JsonLayer::new(subscriber); - /// # - /// # // specifying the Registry type is required - /// # let _: &reload::Handle = &reload_handle; - /// # + /// let layer = json_subscriber::JsonLayer::stdout().with_writer(non_blocking(std::io::stderr())); + /// let (layer, reload_handle) = reload::Layer::new(layer); + /// + /// tracing_subscriber::registry().with(layer).init(); + /// /// info!("This will be logged to stderr"); /// reload_handle.modify(|subscriber| *subscriber.writer_mut() = non_blocking(std::io::stdout())); /// info!("This will be logged to stdout"); @@ -294,14 +289,10 @@ where /// Using [`TestWriter`] to let `cargo test` capture test output: /// /// ```rust - /// use std::io; - /// use tracing_subscriber::fmt; - /// - /// let fmt_subscriber = fmt::subscriber() + /// # use tracing_subscriber::prelude::*; + /// let layer = json_subscriber::JsonLayer::stdout() /// .with_test_writer(); - /// # // this is necessary for type inference. - /// # use tracing_subscriber::Subscribe as _; - /// # let _ = fmt_subscriber.with_collector(tracing_subscriber::registry::Registry::default()); + /// # tracing_subscriber::registry().with(layer); /// ``` /// [capturing]: /// https://doc.rust-lang.org/book/ch11-02-running-tests.html#showing-function-output @@ -338,15 +329,13 @@ where /// Redirect output to stderr if level is <= WARN: /// /// ```rust - /// use tracing::Level; - /// use tracing_subscriber::fmt::{self, writer::MakeWriterExt}; + /// # use tracing_subscriber::prelude::*; + /// use tracing_subscriber::fmt::writer::MakeWriterExt; /// - /// let stderr = std::io::stderr.with_max_level(Level::WARN); - /// let subscriber = fmt::subscriber() + /// let stderr = std::io::stderr.with_max_level(tracing::Level::WARN); + /// let layer = json_subscriber::JsonLayer::stdout() /// .map_writer(move |w| stderr.or_else(w)); - /// # // this is necessary for type inference. - /// # use tracing_subscriber::Subscribe as _; - /// # let _ = subscriber.with_collector(tracing_subscriber::registry::Registry::default()); + /// # tracing_subscriber::registry().with(layer); /// ``` pub fn map_writer(self, f: impl FnOnce(W) -> W2) -> JsonLayer where @@ -367,7 +356,6 @@ where /// /// ```rust /// # use tracing_subscriber::prelude::*; - /// # use tracing_subscriber::registry; /// let mut layer = json_subscriber::JsonLayer::stdout(); /// layer.add_static_field( /// "hostname", @@ -375,8 +363,7 @@ where /// "hostname": get_hostname(), /// }), /// ); - /// - /// registry().with(layer); + /// # tracing_subscriber::registry().with(layer); /// # fn get_hostname() -> &'static str { "localhost" } /// ``` pub fn add_static_field(&mut self, key: impl Into, value: serde_json::Value) { @@ -397,7 +384,6 @@ where /// /// ```rust /// # use tracing_subscriber::prelude::*; - /// # use tracing_subscriber::registry; /// let mut layer = json_subscriber::JsonLayer::stdout(); /// layer.add_static_field( /// "deleteMe", @@ -405,7 +391,7 @@ where /// ); /// layer.remove_field("deleteMe"); /// - /// registry().with(layer); + /// # tracing_subscriber::registry().with(layer); /// ``` pub fn remove_field(&mut self, key: impl Into) { self.schema.remove(&SchemaKey::from(key.into())); diff --git a/src/lib.rs b/src/lib.rs index a5009fc..cfd6647 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -21,7 +21,8 @@ //! ```rust //! use tracing::info; //! use json_subscriber; -//! +//! # +//! # mod yak_shave { pub fn shave_all(n: u32) -> u32 { n } } //! //! // install global collector configured based on RUST_LOG env var. //! json_subscriber::fmt::init(); @@ -63,6 +64,8 @@ //! `tracing-opentelemetry` layer. //! //! ```rust +//! # #[cfg(opentelemetry)] +//! # { //! let tracer = todo!(); //! let opentelemetry = tracing_opentelemetry::layer().with_tracer(tracer); //! let json = json_subscriber::layer() @@ -74,6 +77,7 @@ //! .with(opentelemetry) //! .with(json) //! .init(); +//! # } //! ``` //! //! This will produce log lines like for example this (without the formatting):