Struct tracing_subscriber::fmt::SubscriberBuilder

source ·
pub struct SubscriberBuilder<N = DefaultFields, E = Format<Full>, F = LevelFilter, W = fn() -> Stdout> { /* private fields */ }
Expand description

Configures and constructs Subscribers.

Implementations§

source§

impl<N, E, F, W> SubscriberBuilder<N, E, F, W>
where N: for<'writer> FormatFields<'writer> + 'static, E: FormatEvent<Registry, N> + 'static, W: for<'writer> MakeWriter<'writer> + 'static, F: Layer<Formatter<N, E, W>> + Send + Sync + 'static, Layer<Registry, N, E, W>: Layer<Registry> + Send + Sync + 'static,

source

pub fn finish(self) -> Subscriber<N, E, F, W>

Finish the builder, returning a new FmtSubscriber.

source

pub fn try_init(self) -> Result<(), Box<dyn Error + Send + Sync + 'static>>

Install this Subscriber as the global default if one is not already set.

If the tracing-log feature is enabled, this will also install the LogTracer to convert Log records into tracing Events.

§Errors

Returns an Error if the initialization was unsuccessful, likely because a global subscriber was already installed by another call to try_init.

source

pub fn init(self)

Install this Subscriber as the global default.

If the tracing-log feature is enabled, this will also install the LogTracer to convert Log records into tracing Events.

§Panics

Panics if the initialization was unsuccessful, likely because a global subscriber was already installed by another call to try_init.

source§

impl<N, L, T, F, W> SubscriberBuilder<N, Format<L, T>, F, W>
where N: for<'writer> FormatFields<'writer> + 'static,

source

pub fn with_timer<T2>( self, timer: T2, ) -> SubscriberBuilder<N, Format<L, T2>, F, W>

Use the given timer for log message timestamps.

See the time module for the provided timer implementations.

Note that using the "time“” feature flag enables the additional time formatters UtcTime and LocalTime, which use the time crate to provide more sophisticated timestamp formatting options.

source

pub fn without_time(self) -> SubscriberBuilder<N, Format<L, ()>, F, W>

Do not emit timestamps with log messages.

source

pub fn with_span_events(self, kind: FmtSpan) -> Self

Configures how synthesized events are emitted at points in the span lifecycle.

The following options are available:

  • FmtSpan::NONE: No events will be synthesized when spans are created, entered, exited, or closed. Data from spans will still be included as the context for formatted events. This is the default.
  • FmtSpan::NEW: An event will be synthesized when spans are created.
  • FmtSpan::ENTER: An event will be synthesized when spans are entered.
  • FmtSpan::EXIT: An event will be synthesized when spans are exited.
  • FmtSpan::CLOSE: An event will be synthesized when a span closes. If timestamps are enabled for this formatter, the generated event will contain fields with the span’s busy time (the total time for which it was entered) and idle time (the total time that the span existed but was not entered).
  • FmtSpan::ACTIVE: An event will be synthesized when spans are entered or exited.
  • FmtSpan::FULL: Events will be synthesized whenever a span is created, entered, exited, or closed. If timestamps are enabled, the close event will contain the span’s busy and idle time, as described above.

The options can be enabled in any combination. For instance, the following will synthesize events whenever spans are created and closed:

use tracing_subscriber::fmt::format::FmtSpan;
use tracing_subscriber::fmt;

let subscriber = fmt()
    .with_span_events(FmtSpan::NEW | FmtSpan::CLOSE)
    .finish();

Note that the generated events will only be part of the log output by this formatter; they will not be recorded by other Subscribers or by Layers added to this subscriber.

source

pub fn with_ansi(self, ansi: bool) -> SubscriberBuilder<N, Format<L, T>, F, W>

Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting.

Enabling ANSI escapes (calling with_ansi(true)) requires the “ansi” crate feature flag. Calling with_ansi(true) without the “ansi” feature flag enabled will panic if debug assertions are enabled, or print a warning otherwise.

This method itself is still available without the feature flag. This is to allow ANSI escape codes to be explicitly disabled without having to opt-in to the dependencies required to emit ANSI formatting. This way, code which constructs a formatter that should never emit ANSI escape codes can ensure that they are not used, regardless of whether or not other crates in the dependency graph enable the “ansi” feature flag.

source

pub fn log_internal_errors( self, log_internal_errors: bool, ) -> SubscriberBuilder<N, Format<L, T>, F, W>

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.

source

pub fn with_target( self, display_target: bool, ) -> SubscriberBuilder<N, Format<L, T>, F, W>

Sets whether or not an event’s target is displayed.

source

pub fn with_file( self, display_filename: bool, ) -> SubscriberBuilder<N, Format<L, T>, F, W>

Sets whether or not an event’s source code file path is displayed.

source

pub fn with_line_number( self, display_line_number: bool, ) -> SubscriberBuilder<N, Format<L, T>, F, W>

Sets whether or not an event’s source code line number is displayed.

source

pub fn with_level( self, display_level: bool, ) -> SubscriberBuilder<N, Format<L, T>, F, W>

Sets whether or not an event’s level is displayed.

source

pub fn with_thread_names( self, display_thread_names: bool, ) -> SubscriberBuilder<N, Format<L, T>, F, W>

Sets whether or not the name of the current thread is displayed when formatting events.

source

pub fn with_thread_ids( self, display_thread_ids: bool, ) -> SubscriberBuilder<N, Format<L, T>, F, W>

Sets whether or not the thread ID of the current thread is displayed when formatting events.

source

pub fn compact(self) -> SubscriberBuilder<N, Format<Compact, T>, F, W>
where N: for<'writer> FormatFields<'writer> + 'static,

Sets the subscriber being built to use a less verbose formatter.

See format::Compact.

source

pub fn pretty(self) -> SubscriberBuilder<Pretty, Format<Pretty, T>, F, W>

Sets the subscriber being built to use an excessively pretty, human-readable formatter.

source§

impl<N, E, W> SubscriberBuilder<N, E, EnvFilter, W>
where Formatter<N, E, W>: Subscriber + 'static,

source

pub fn with_filter_reloading( self, ) -> SubscriberBuilder<N, E, Layer<EnvFilter, Formatter<N, E, W>>, W>

Configures the subscriber being built to allow filter reloading at runtime.

source§

impl<N, E, W> SubscriberBuilder<N, E, Layer<EnvFilter, Formatter<N, E, W>>, W>
where Formatter<N, E, W>: Subscriber + 'static,

source

pub fn reload_handle(&self) -> Handle<EnvFilter, Formatter<N, E, W>>

Returns a Handle that may be used to reload the constructed subscriber’s filter.

source§

impl<N, E, F, W> SubscriberBuilder<N, E, F, W>

source

pub fn fmt_fields<N2>(self, fmt_fields: N2) -> SubscriberBuilder<N2, E, F, W>
where N2: for<'writer> FormatFields<'writer> + 'static,

Sets the field formatter that the subscriber being built will use to record fields.

For example:

use tracing_subscriber::fmt::format;
use tracing_subscriber::prelude::*;

let formatter =
    // Construct a custom formatter for `Debug` fields
    format::debug_fn(|writer, field, value| write!(writer, "{}: {:?}", field, value))
        // Use the `tracing_subscriber::MakeFmtExt` trait to wrap the
        // formatter so that a delimiter is added between fields.
        .delimited(", ");

let subscriber = tracing_subscriber::fmt()
    .fmt_fields(formatter)
    .finish();
source

pub fn with_env_filter( self, filter: impl Into<EnvFilter>, ) -> SubscriberBuilder<N, E, EnvFilter, W>
where Formatter<N, E, W>: Subscriber + 'static,

Sets the EnvFilter that the subscriber will use to determine if a span or event is enabled.

Note that this method requires the “env-filter” feature flag to be enabled.

If a filter was previously set, or a maximum level was set by the with_max_level method, that value is replaced by the new filter.

§Examples

Setting a filter based on the value of the RUST_LOG environment variable:

use tracing_subscriber::{fmt, EnvFilter};

fmt()
    .with_env_filter(EnvFilter::from_default_env())
    .init();

Setting a filter based on a pre-set filter directive string:

use tracing_subscriber::fmt;

fmt()
    .with_env_filter("my_crate=info,my_crate::my_mod=debug,[my_span]=trace")
    .init();

Adding additional directives to a filter constructed from an env var:

use tracing_subscriber::{fmt, filter::{EnvFilter, LevelFilter}};

let filter = EnvFilter::try_from_env("MY_CUSTOM_FILTER_ENV_VAR")?
    // Set the base level when not matched by other directives to WARN.
    .add_directive(LevelFilter::WARN.into())
    // Set the max level for `my_crate::my_mod` to DEBUG, overriding
    // any directives parsed from the env variable.
    .add_directive("my_crate::my_mod=debug".parse()?);

fmt()
    .with_env_filter(filter)
    .try_init()?;
source

pub fn with_max_level( self, filter: impl Into<LevelFilter>, ) -> SubscriberBuilder<N, E, LevelFilter, W>

Sets the maximum verbosity level that will be enabled by the subscriber.

If the max level has already been set, or a EnvFilter was added by with_env_filter, this replaces that configuration with the new maximum level.

§Examples

Enable up to the DEBUG verbosity level:

use tracing_subscriber::fmt;
use tracing::Level;

fmt()
    .with_max_level(Level::DEBUG)
    .init();

This subscriber won’t record any spans or events!

use tracing_subscriber::{fmt, filter::LevelFilter};

let subscriber = fmt()
    .with_max_level(LevelFilter::OFF)
    .finish();
source

pub fn event_format<E2>(self, fmt_event: E2) -> SubscriberBuilder<N, E2, F, W>
where E2: FormatEvent<Registry, N> + 'static, N: for<'writer> FormatFields<'writer> + 'static, W: for<'writer> MakeWriter<'writer> + 'static,

Sets the event formatter 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:

use tracing_subscriber::fmt::format;

let subscriber = tracing_subscriber::fmt()
    .event_format(format().compact())
    .finish();
source

pub fn with_writer<W2>(self, make_writer: W2) -> SubscriberBuilder<N, E, F, W2>
where W2: for<'writer> MakeWriter<'writer> + 'static,

Sets the MakeWriter that the subscriber being built will use to write events.

§Examples

Using stderr rather than stdout:

use tracing_subscriber::fmt;
use std::io;

fmt()
    .with_writer(io::stderr)
    .init();
source

pub fn with_test_writer(self) -> SubscriberBuilder<N, E, F, TestWriter>

Configures the subscriber to support libtest’s output capturing when used in unit tests.

See TestWriter for additional details.

§Examples

Using TestWriter to let cargo test capture test output. Note that we do not install it globally as it may cause conflicts.

use tracing_subscriber::fmt;
use tracing::subscriber;

subscriber::set_default(
    fmt()
        .with_test_writer()
        .finish()
);
source

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,

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:

let subscriber = tracing_subscriber::fmt()
    .map_event_format(|e| e.compact())
    .finish();
source

pub fn map_fmt_fields<N2>( self, f: impl FnOnce(N) -> N2, ) -> SubscriberBuilder<N2, E, F, W>
where N2: for<'writer> FormatFields<'writer> + 'static,

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:

use tracing_subscriber::field::MakeExt;
let subscriber = tracing_subscriber::fmt()
    .map_fmt_fields(|f| f.debug_alt())
    .finish();
source

pub fn map_writer<W2>( self, f: impl FnOnce(W) -> W2, ) -> SubscriberBuilder<N, E, F, W2>
where W2: for<'writer> MakeWriter<'writer> + 'static,

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:

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();

Trait Implementations§

source§

impl<N: Debug, E: Debug, F: Debug, W: Debug> Debug for SubscriberBuilder<N, E, F, W>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl Default for SubscriberBuilder

source§

fn default() -> Self

Returns the “default value” for a type. Read more
source§

impl<N, E, F, W> From<SubscriberBuilder<N, E, F, W>> for Dispatch
where N: for<'writer> FormatFields<'writer> + 'static, E: FormatEvent<Registry, N> + 'static, W: for<'writer> MakeWriter<'writer> + 'static, F: Layer<Formatter<N, E, W>> + Send + Sync + 'static, Layer<Registry, N, E, W>: Layer<Registry> + Send + Sync + 'static,

source§

fn from(builder: SubscriberBuilder<N, E, F, W>) -> Dispatch

Converts to this type from the input type.

Auto Trait Implementations§

§

impl<N, E, F, W> Freeze for SubscriberBuilder<N, E, F, W>
where F: Freeze, W: Freeze, N: Freeze, E: Freeze,

§

impl<N, E, F, W> RefUnwindSafe for SubscriberBuilder<N, E, F, W>

§

impl<N, E, F, W> Send for SubscriberBuilder<N, E, F, W>
where F: Send, W: Send, N: Send, E: Send,

§

impl<N, E, F, W> Sync for SubscriberBuilder<N, E, F, W>
where F: Sync, W: Sync, N: Sync, E: Sync,

§

impl<N, E, F, W> Unpin for SubscriberBuilder<N, E, F, W>
where F: Unpin, W: Unpin, N: Unpin, E: Unpin,

§

impl<N, E, F, W> UnwindSafe for SubscriberBuilder<N, E, F, W>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> SubscriberInitExt for T
where T: Into<Dispatch>,

source§

fn set_default(self) -> DefaultGuard

Sets self as the default subscriber in the current scope, returning a guard that will unset it when dropped. Read more
source§

fn try_init(self) -> Result<(), TryInitError>

Attempts to set self as the global default subscriber in the current scope, returning an error if one is already set. Read more
source§

fn init(self)

Attempts to set self as the global default subscriber in the current scope, panicking if this fails. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more