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 Subscriber
s.
Implementations
sourceimpl<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,
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,
sourcepub fn finish(self) -> Subscriber<N, E, F, W>
pub fn finish(self) -> Subscriber<N, E, F, W>
Finish the builder, returning a new FmtSubscriber
.
sourcepub fn try_init(self) -> Result<(), Box<dyn Error + Send + Sync + 'static>>
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
Event
s.
Errors
Returns an Error if the initialization was unsuccessful, likely
because a global subscriber was already installed by another
call to try_init
.
sourcepub fn init(self)
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
Event
s.
Panics
Panics if the initialization was unsuccessful, likely because a
global subscriber was already installed by another call to try_init
.
sourceimpl<N, L, T, F, W> SubscriberBuilder<N, Format<L, T>, F, W> where
N: for<'writer> FormatFields<'writer> + 'static,
impl<N, L, T, F, W> SubscriberBuilder<N, Format<L, T>, F, W> where
N: for<'writer> FormatFields<'writer> + 'static,
sourcepub fn with_timer<T2>(
self,
timer: T2
) -> SubscriberBuilder<N, Format<L, T2>, F, W>
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.
sourcepub fn without_time(self) -> SubscriberBuilder<N, Format<L, ()>, F, W>
pub fn without_time(self) -> SubscriberBuilder<N, Format<L, ()>, F, W>
Do not emit timestamps with log messages.
sourcepub fn with_span_events(self, kind: FmtSpan) -> Self
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 Subscriber
s or by
Layer
s added to this subscriber.
sourcepub fn with_ansi(self, ansi: bool) -> SubscriberBuilder<N, Format<L, T>, F, W>
pub fn with_ansi(self, ansi: bool) -> SubscriberBuilder<N, Format<L, T>, F, W>
Enable ANSI encoding for formatted events.
sourcepub fn with_target(
self,
display_target: bool
) -> SubscriberBuilder<N, Format<L, T>, F, W>
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.
sourcepub fn with_file(
self,
display_filename: bool
) -> SubscriberBuilder<N, Format<L, T>, F, W>
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.
sourcepub fn with_line_number(
self,
display_line_number: bool
) -> SubscriberBuilder<N, Format<L, T>, F, W>
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.
sourcepub fn with_level(
self,
display_level: bool
) -> SubscriberBuilder<N, Format<L, T>, F, W>
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.
sourcepub fn with_thread_names(
self,
display_thread_names: bool
) -> SubscriberBuilder<N, Format<L, T>, F, W>
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
sourcepub fn with_thread_ids(
self,
display_thread_ids: bool
) -> SubscriberBuilder<N, Format<L, T>, F, W>
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
sourcepub fn compact(self) -> SubscriberBuilder<N, Format<Compact, T>, F, W> where
N: for<'writer> FormatFields<'writer> + 'static,
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
.
sourcepub fn pretty(self) -> SubscriberBuilder<Pretty, Format<Pretty, T>, F, W>
pub fn pretty(self) -> SubscriberBuilder<Pretty, Format<Pretty, T>, F, W>
Sets the subscriber being built to use an excessively pretty, human-readable formatter.
sourceimpl<N, E, F, W> SubscriberBuilder<N, E, F, W>
impl<N, E, F, W> SubscriberBuilder<N, E, F, W>
sourcepub fn fmt_fields<N2>(self, fmt_fields: N2) -> SubscriberBuilder<N2, E, F, W> where
N2: for<'writer> FormatFields<'writer> + 'static,
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();
sourcepub fn with_max_level(
self,
filter: impl Into<LevelFilter>
) -> SubscriberBuilder<N, E, LevelFilter, W>
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();
sourcepub 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,
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();
sourcepub fn with_writer<W2>(self, make_writer: W2) -> SubscriberBuilder<N, E, F, W2> where
W2: for<'writer> MakeWriter<'writer> + 'static,
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();
sourcepub fn with_test_writer(self) -> SubscriberBuilder<N, E, F, TestWriter>
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()
);
sourcepub 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,
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();
sourcepub fn map_fmt_fields<N2>(
self,
f: impl FnOnce(N) -> N2
) -> SubscriberBuilder<N2, E, F, W> where
N2: for<'writer> FormatFields<'writer> + 'static,
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();
sourcepub fn map_writer<W2>(
self,
f: impl FnOnce(W) -> W2
) -> SubscriberBuilder<N, E, F, W2> where
W2: for<'writer> MakeWriter<'writer> + 'static,
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
sourceimpl Default for SubscriberBuilder
impl Default for SubscriberBuilder
sourceimpl<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,
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,
sourcefn from(builder: SubscriberBuilder<N, E, F, W>) -> Dispatch
fn from(builder: SubscriberBuilder<N, E, F, W>) -> Dispatch
Performs the conversion.
Auto Trait Implementations
impl<N, E, F, W> RefUnwindSafe for SubscriberBuilder<N, E, F, W> where
E: RefUnwindSafe,
F: RefUnwindSafe,
N: RefUnwindSafe,
W: RefUnwindSafe,
impl<N, E, F, W> Send for SubscriberBuilder<N, E, F, W> where
E: Send,
F: Send,
N: Send,
W: Send,
impl<N, E, F, W> Sync for SubscriberBuilder<N, E, F, W> where
E: Sync,
F: Sync,
N: Sync,
W: Sync,
impl<N, E, F, W> Unpin for SubscriberBuilder<N, E, F, W> where
E: Unpin,
F: Unpin,
N: Unpin,
W: Unpin,
impl<N, E, F, W> UnwindSafe for SubscriberBuilder<N, E, F, W> where
E: UnwindSafe,
F: UnwindSafe,
N: UnwindSafe,
W: UnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> SubscriberInitExt for T where
T: Into<Dispatch>,
impl<T> SubscriberInitExt for T where
T: Into<Dispatch>,
sourcefn set_default(self) -> DefaultGuard
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
sourcefn try_init(self) -> Result<(), TryInitError>
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
sourcefn init(self)
fn init(self)
Attempts to set self
as the global default subscriber in the current
scope, panicking if this fails. Read more