pub struct Subscriber<C, N = DefaultFields, E = Format, W = fn() -> Stdout> { /* private fields */ }
fmt
and std
only.Expand description
A Subscriber
that logs formatted representations of tracing
events.
§Examples
Constructing a subscriber with the default configuration:
use tracing_subscriber::{fmt, Registry};
use tracing_subscriber::subscribe::CollectExt;
let collector = Registry::default()
.with(fmt::Subscriber::default());
tracing::collect::set_global_default(collector).unwrap();
Overriding the subscriber’s behavior:
use tracing_subscriber::{fmt, Registry};
use tracing_subscriber::subscribe::CollectExt;
let fmt_subscriber = fmt::subscriber()
.with_target(false) // don't include event targets when logging
.with_level(false); // don't include event levels when logging
let collector = Registry::default().with(fmt_subscriber);
Setting a custom event formatter:
use tracing_subscriber::fmt::{self, format, time};
use tracing_subscriber::Subscribe;
let fmt = format().with_timer(time::Uptime::default());
let fmt_subscriber = fmt::subscriber()
.event_format(fmt)
.with_target(false);
Implementations§
Source§impl<C> Subscriber<C>
impl<C> Subscriber<C>
Sourcepub fn new() -> Self
pub fn new() -> Self
Returns a new Subscriber
with the default configuration.
Source§impl<C, N, E, W> Subscriber<C, N, E, W>where
C: Collect + for<'a> LookupSpan<'a>,
N: for<'writer> FormatFields<'writer> + 'static,
W: for<'writer> MakeWriter<'writer> + 'static,
impl<C, N, E, W> Subscriber<C, N, E, W>where
C: Collect + for<'a> LookupSpan<'a>,
N: for<'writer> FormatFields<'writer> + 'static,
W: for<'writer> MakeWriter<'writer> + 'static,
Sourcepub fn event_format<E2>(self, e: E2) -> Subscriber<C, N, E2, W> ⓘwhere
E2: FormatEvent<C, N> + 'static,
pub fn event_format<E2>(self, e: E2) -> Subscriber<C, N, E2, W> ⓘwhere
E2: FormatEvent<C, N> + 'static,
Sets the event formatter that the subscriber will use to format events.
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::{self, format};
let fmt_subscriber = fmt::subscriber()
.event_format(format().compact());
Sourcepub fn map_event_format<E2>(
self,
f: impl FnOnce(E) -> E2,
) -> Subscriber<C, N, E2, W> ⓘwhere
E2: FormatEvent<C, N> + 'static,
pub fn map_event_format<E2>(
self,
f: impl FnOnce(E) -> E2,
) -> Subscriber<C, N, E2, W> ⓘwhere
E2: FormatEvent<C, N> + '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::subscriber()
.map_event_format(|e| e.compact());
Source§impl<C, N, E, W> Subscriber<C, N, E, W>
impl<C, N, E, W> Subscriber<C, N, E, W>
Sourcepub fn with_writer<W2>(self, make_writer: W2) -> Subscriber<C, N, E, W2> ⓘwhere
W2: for<'writer> MakeWriter<'writer> + 'static,
pub fn with_writer<W2>(self, make_writer: W2) -> Subscriber<C, N, E, 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 std::io;
use tracing_subscriber::fmt;
let fmt_subscriber = fmt::subscriber()
.with_writer(io::stderr);
Sourcepub fn writer_mut(&mut self) -> &mut W
pub fn writer_mut(&mut self) -> &mut W
Mutably borrows the writer for this subscriber.
This method is primarily expected to be used with the
reload::Handle::modify
method.
§Examples
let subscriber = fmt::subscriber().with_writer(non_blocking(std::io::stderr()));
let (subscriber, reload_handle) = reload::Subscriber::new(subscriber);
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");
Sourcepub fn set_ansi(&mut self, ansi: bool)
Available on crate feature ansi
only.
pub fn set_ansi(&mut self, ansi: bool)
ansi
only.Sets whether this subscriber should use ANSI terminal formatting escape codes (such as colors).
This method is primarily expected to be used with the
reload::Handle::modify
method when changing
the writer.
Sourcepub fn set_span_events(&mut self, kind: FmtSpan)
pub fn set_span_events(&mut self, kind: FmtSpan)
Modifies how synthesized events are emitted at points in the span lifecycle.
See Self::with_span_events
for documentation on the FmtSpan
This method is primarily expected to be used with the
reload::Handle::modify
method
Note that using this method modifies the span configuration instantly and does not take into
account any current spans. If the previous configuration was set to capture
FmtSpan::ALL
, for example, using this method to change to FmtSpan::NONE
will cause an
exit event for currently entered events not to be formatted
Sourcepub fn with_test_writer(self) -> Subscriber<C, N, E, TestWriter> ⓘ
pub fn with_test_writer(self) -> Subscriber<C, N, E, 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:
use std::io;
use tracing_subscriber::fmt;
let fmt_subscriber = fmt::subscriber()
.with_test_writer();
Sourcepub fn with_ansi(self, ansi: bool) -> Self
pub fn with_ansi(self, ansi: bool) -> Self
Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting.
When the “ansi” crate feature flag is enabled, ANSI colors are enabled
by default unless the NO_COLOR
environment variable is set to
a non-empty value. If the NO_COLOR
environment variable is set to
any non-empty value, then ANSI colors will be suppressed by default.
The with_ansi
and set_ansi
methods can be used to forcibly
enable ANSI colors, overriding any NO_COLOR
environment variable.
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.
Sourcepub fn log_internal_errors(self, log_internal_errors: bool) -> Self
pub fn log_internal_errors(self, log_internal_errors: bool) -> Self
Sets whether to write errors from FormatEvent
to the writer.
Defaults to true.
By default, fmt::Subscriber
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.
Sourcepub fn map_writer<W2>(self, f: impl FnOnce(W) -> W2) -> Subscriber<C, N, E, W2> ⓘwhere
W2: for<'writer> MakeWriter<'writer> + 'static,
pub fn map_writer<W2>(self, f: impl FnOnce(W) -> W2) -> Subscriber<C, N, E, 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 subscriber = fmt::subscriber()
.map_writer(move |w| stderr.or_else(w));
Source§impl<C, N, L, T, W> Subscriber<C, N, Format<L, T>, W>where
N: for<'writer> FormatFields<'writer> + 'static,
impl<C, N, L, T, W> Subscriber<C, N, Format<L, T>, W>where
N: for<'writer> FormatFields<'writer> + 'static,
Sourcepub fn with_timer<T2>(self, timer: T2) -> Subscriber<C, N, Format<L, T2>, W> ⓘ
pub fn with_timer<T2>(self, timer: T2) -> Subscriber<C, N, Format<L, T2>, W> ⓘ
Use the given timer
for span and event 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) -> Subscriber<C, N, Format<L, ()>, W> ⓘ
pub fn without_time(self) -> Subscriber<C, N, Format<L, ()>, W> ⓘ
Do not emit timestamps with spans and event.
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
: Events 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;
use tracing_subscriber::fmt::format::FmtSpan;
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 Collector
s or by
Subscriber
s added to this subscriber.
Sourcepub fn with_target(
self,
display_target: bool,
) -> Subscriber<C, N, Format<L, T>, W> ⓘ
pub fn with_target( self, display_target: bool, ) -> Subscriber<C, N, Format<L, T>, W> ⓘ
Sets whether or not an event’s target is displayed.
Sourcepub fn with_file(
self,
display_filename: bool,
) -> Subscriber<C, N, Format<L, T>, W> ⓘ
pub fn with_file( self, display_filename: bool, ) -> Subscriber<C, N, Format<L, T>, W> ⓘ
Sets whether or not an event’s source code file path is displayed.
Sourcepub fn with_line_number(
self,
display_line_number: bool,
) -> Subscriber<C, N, Format<L, T>, W> ⓘ
pub fn with_line_number( self, display_line_number: bool, ) -> Subscriber<C, N, Format<L, T>, W> ⓘ
Sets whether or not an event’s source code line number is displayed.
Sourcepub fn with_level(
self,
display_level: bool,
) -> Subscriber<C, N, Format<L, T>, W> ⓘ
pub fn with_level( self, display_level: bool, ) -> Subscriber<C, N, Format<L, T>, W> ⓘ
Sets whether or not an event’s level is displayed.
Sourcepub fn with_thread_ids(
self,
display_thread_ids: bool,
) -> Subscriber<C, N, Format<L, T>, W> ⓘ
pub fn with_thread_ids( self, display_thread_ids: bool, ) -> Subscriber<C, N, Format<L, T>, W> ⓘ
Sets whether or not the thread ID of the current thread is displayed when formatting events.
Sourcepub fn with_thread_names(
self,
display_thread_names: bool,
) -> Subscriber<C, N, Format<L, T>, W> ⓘ
pub fn with_thread_names( self, display_thread_names: bool, ) -> Subscriber<C, N, Format<L, T>, W> ⓘ
Sets whether or not the name of the current thread is displayed when formatting events.
Sourcepub fn compact(self) -> Subscriber<C, N, Format<Compact, T>, W> ⓘwhere
N: for<'writer> FormatFields<'writer> + 'static,
pub fn compact(self) -> Subscriber<C, N, Format<Compact, T>, W> ⓘwhere
N: for<'writer> FormatFields<'writer> + 'static,
Sets the subscriber being built to use a less verbose formatter.
Sourcepub fn pretty(self) -> Subscriber<C, Pretty, Format<Pretty, T>, W> ⓘ
Available on crate feature ansi
only.
pub fn pretty(self) -> Subscriber<C, Pretty, Format<Pretty, T>, W> ⓘ
ansi
only.Sets the subscriber being built to use an excessively pretty, human-readable formatter.
Sourcepub fn json(self) -> Subscriber<C, JsonFields, Format<Json, T>, W> ⓘ
Available on crate feature json
only.
pub fn json(self) -> Subscriber<C, JsonFields, Format<Json, T>, W> ⓘ
json
only.Sets the subscriber being built to use a JSON formatter.
The full format includes fields from all entered spans.
§Example Output
{"timestamp":"Feb 20 11:28:15.096","level":"INFO","target":"mycrate","fields":{"message":"some message", "key": "value"}}
§Options
Subscriber::flatten_event
can be used to enable flattening event fields into the root object.
Source§impl<C, T, W> Subscriber<C, JsonFields, Format<Json, T>, W>
impl<C, T, W> Subscriber<C, JsonFields, Format<Json, T>, W>
Sourcepub fn flatten_event(
self,
flatten_event: bool,
) -> Subscriber<C, JsonFields, Format<Json, T>, W> ⓘ
Available on crate feature json
only.
pub fn flatten_event( self, flatten_event: bool, ) -> Subscriber<C, JsonFields, Format<Json, T>, W> ⓘ
json
only.Sets the JSON subscriber being built to flatten event metadata.
See format::Json
Sourcepub fn with_current_span(
self,
display_current_span: bool,
) -> Subscriber<C, JsonFields, Format<Json, T>, W> ⓘ
Available on crate feature json
only.
pub fn with_current_span( self, display_current_span: bool, ) -> Subscriber<C, JsonFields, Format<Json, T>, W> ⓘ
json
only.Sets whether or not the formatter will include the current span in formatted events.
See format::Json
Sourcepub fn with_span_list(
self,
display_span_list: bool,
) -> Subscriber<C, JsonFields, Format<Json, T>, W> ⓘ
Available on crate feature json
only.
pub fn with_span_list( self, display_span_list: bool, ) -> Subscriber<C, JsonFields, Format<Json, T>, W> ⓘ
json
only.Sets whether or not the formatter will include a list (from root to leaf) of all currently entered spans in formatted events.
See format::Json
Source§impl<C, N, E, W> Subscriber<C, N, E, W>
impl<C, N, E, W> Subscriber<C, N, E, W>
Sourcepub fn fmt_fields<N2>(self, fmt_fields: N2) -> Subscriber<C, N2, E, W> ⓘwhere
N2: for<'writer> FormatFields<'writer> + 'static,
pub fn fmt_fields<N2>(self, fmt_fields: N2) -> Subscriber<C, N2, E, W> ⓘwhere
N2: for<'writer> FormatFields<'writer> + 'static,
Sets the field formatter that the subscriber being built will use to record fields.
Sourcepub fn map_fmt_fields<N2>(
self,
f: impl FnOnce(N) -> N2,
) -> Subscriber<C, N2, E, W> ⓘwhere
N2: for<'writer> FormatFields<'writer> + 'static,
pub fn map_fmt_fields<N2>(
self,
f: impl FnOnce(N) -> N2,
) -> Subscriber<C, N2, E, 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::subscriber()
.map_fmt_fields(|f| f.debug_alt());
Trait Implementations§
Source§impl<C> Default for Subscriber<C>
impl<C> Default for Subscriber<C>
Source§impl<C, N, E, W> Subscribe<C> for Subscriber<C, N, E, W>where
C: Collect + for<'a> LookupSpan<'a>,
N: for<'writer> FormatFields<'writer> + 'static,
E: FormatEvent<C, N> + 'static,
W: for<'writer> MakeWriter<'writer> + 'static,
impl<C, N, E, W> Subscribe<C> for Subscriber<C, N, E, W>where
C: Collect + for<'a> LookupSpan<'a>,
N: for<'writer> FormatFields<'writer> + 'static,
E: FormatEvent<C, N> + 'static,
W: for<'writer> MakeWriter<'writer> + 'static,
Source§fn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, C>)
fn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, C>)
Attributes
and Id
.Source§fn on_record(&self, id: &Id, values: &Record<'_>, ctx: Context<'_, C>)
fn on_record(&self, id: &Id, values: &Record<'_>, ctx: Context<'_, C>)
Id
recorded the given
values
.Source§fn on_enter(&self, id: &Id, ctx: Context<'_, C>)
fn on_enter(&self, id: &Id, ctx: Context<'_, C>)
Source§fn on_exit(&self, id: &Id, ctx: Context<'_, C>)
fn on_exit(&self, id: &Id, ctx: Context<'_, C>)
Source§fn on_close(&self, id: Id, ctx: Context<'_, C>)
fn on_close(&self, id: Id, ctx: Context<'_, C>)
Source§fn on_event(&self, event: &Event<'_>, ctx: Context<'_, C>)
fn on_event(&self, event: &Event<'_>, ctx: Context<'_, C>)
Source§fn on_register_dispatch(&self, collector: &Dispatch)
fn on_register_dispatch(&self, collector: &Dispatch)
Source§fn on_subscribe(&mut self, collector: &mut C)
fn on_subscribe(&mut self, collector: &mut C)
Source§fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest
fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest
Collect::register_callsite
. Read moreSource§fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, C>) -> bool
fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, C>) -> bool
true
if this subscriber is interested in a span or event with the
given metadata
in the current Context
, similarly to
Collect::enabled
. Read moreSource§fn on_follows_from(&self, _span: &Id, _follows: &Id, _ctx: Context<'_, C>)
fn on_follows_from(&self, _span: &Id, _follows: &Id, _ctx: Context<'_, C>)
span
recorded that it
follows from the span with the ID follows
.Source§fn on_id_change(&self, _old: &Id, _new: &Id, _ctx: Context<'_, C>)
fn on_id_change(&self, _old: &Id, _new: &Id, _ctx: Context<'_, C>)
Source§fn and_then<S>(self, subscriber: S) -> Layered<S, Self, C> ⓘ
fn and_then<S>(self, subscriber: S) -> Layered<S, Self, C> ⓘ
Layered
struct implementing Subscribe
. Read moreSource§fn with_filter<F>(self, filter: F) -> Filtered<Self, F, C> ⓘ
fn with_filter<F>(self, filter: F) -> Filtered<Self, F, C> ⓘ
registry
only.