Struct tracing_subscriber::fmt::Layer

pub struct Layer<S, N = DefaultFields, E = Format<Full>, W = fn() -> Stdout> { /* private fields */ }

A Layer that logs formatted representations of tracing events.

Examples

Constructing a layer with the default configuration:

use tracing_subscriber::{fmt, Registry};
use tracing_subscriber::prelude::*;

let subscriber = Registry::default()
    .with(fmt::Layer::default());

tracing::subscriber::set_global_default(subscriber).unwrap();

Overriding the layer’s behavior:

use tracing_subscriber::{fmt, Registry};
use tracing_subscriber::prelude::*;

let fmt_layer = fmt::layer()
   .with_target(false) // don't include event targets when logging
   .with_level(false); // don't include event levels when logging

let subscriber = Registry::default().with(fmt_layer);

Setting a custom event formatter:

use tracing_subscriber::fmt::{self, format, time};
use tracing_subscriber::prelude::*;

let fmt = format().with_timer(time::Uptime::default());
let fmt_layer = fmt::layer()
    .event_format(fmt)
    .with_target(false);

Implementations

impl<S> Layer<S>

pub fn builder() -> LayerBuilder<S>

👎 Deprecated since 0.2.4:

a separate layer builder is not necessary, use Layer::new/Layer::default instead

Returns a new LayerBuilder for configuring a Layer.

pub fn new() -> Self

Returns a new Layer with the default configuration.

impl<S, N, E, W> Layer<S, N, E, W> where
    S: Subscriber + for<'a> LookupSpan<'a>,
    N: for<'writer> FormatFields<'writer> + 'static,
    W: MakeWriter + 'static, 

pub fn event_format<E2>(self, e: E2) -> Layer<S, N, E2, W> where
    E2: FormatEvent<S, N> + 'static, 

Sets the event formatter that the layer 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 &mut dyn Write, and an Event.

Examples

Setting a type implementing FormatEvent as the formatter:

use tracing_subscriber::fmt::{self, format};

let layer = fmt::layer()
    .event_format(format().compact());

impl<S, N, E, W> Layer<S, N, E, W>

pub fn with_writer<W2>(self, make_writer: W2) -> Layer<S, N, E, W2> where
    W2: MakeWriter + 'static, 

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

Examples

Using stderr rather than stdout:

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

let layer = fmt::layer()
    .with_writer(io::stderr);

pub fn with_test_writer(self) -> Layer<S, 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 layer = fmt::layer()
    .with_test_writer();

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

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

Use the given timer for span and event timestamps.

See time for the provided timer implementations.

Note that using the chrono feature flag enables the additional time formatters ChronoUtc and ChronoLocal.

pub fn without_time(self) -> Layer<S, N, Format<L, ()>, W>

Do not emit timestamps with spans and event.

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 Subscribers or by Layers added to this subscriber.

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

Enable ANSI encoding for formatted events.

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

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

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

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

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

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

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

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

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

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

pub fn pretty(self) -> Layer<S, Pretty, Format<Pretty, T>, W>

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

pub fn json(self) -> Layer<S, JsonFields, Format<Json, T>, W>

Sets the layer 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

• Layer::flatten_event can be used to enable flattening event fields into the root object.

impl<S, T, W> Layer<S, JsonFields, Format<Json, T>, W>

pub fn flatten_event(
    self,
    flatten_event: bool
) -> Layer<S, JsonFields, Format<Json, T>, W>

Sets the JSON layer being built to flatten event metadata.

See format::Json

pub fn with_current_span(
    self,
    display_current_span: bool
) -> Layer<S, JsonFields, Format<Json, T>, W>

Sets whether or not the formatter will include the current span in formatted events.

See format::Json

pub fn with_span_list(
    self,
    display_span_list: bool
) -> Layer<S, JsonFields, Format<Json, T>, W>

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

impl<S, N, E, W> Layer<S, N, E, W>

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

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

impl<S, N, E, W> Layer<S, N, E, W> where
    S: Subscriber + for<'a> LookupSpan<'a>,
    N: for<'writer> FormatFields<'writer> + 'static,
    E: FormatEvent<S, N> + 'static,
    W: MakeWriter + 'static, 

pub fn finish(self) -> Layer<S, N, E, W>

👎 Deprecated since 0.2.4:

LayerBuilder is no longer a separate type; this method is not necessary

Builds a Layer with the provided configuration.

Trait Implementations

impl<S: Debug, N: Debug, E: Debug, W: Debug> Debug for Layer<S, N, E, W>

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

Formats the value using the given formatter.

impl<S> Default for Layer<S>

fn default() -> Self

Returns the “default value” for a type.

impl<S, N, E, W> Layer<S> for Layer<S, N, E, W> where
    S: Subscriber + for<'a> LookupSpan<'a>,
    N: for<'writer> FormatFields<'writer> + 'static,
    E: FormatEvent<S, N> + 'static,
    W: MakeWriter + 'static, 

fn new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, S>)

Notifies this layer that a new span was constructed with the given Attributes and Id.

fn on_record(&self, id: &Id, values: &Record<'_>, ctx: Context<'_, S>)

Notifies this layer that a span with the given Id recorded the given values.

fn on_enter(&self, id: &Id, ctx: Context<'_, S>)

Notifies this layer that a span with the given ID was entered.

fn on_exit(&self, id: &Id, ctx: Context<'_, S>)

Notifies this layer that the span with the given ID was exited.

fn on_close(&self, id: Id, ctx: Context<'_, S>)

Notifies this layer that the span with the given ID has been closed.

fn on_event(&self, event: &Event<'_>, ctx: Context<'_, S>)

Notifies this layer that an event has occurred.

fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest

Registers a new callsite with this layer, returning whether or not the layer is interested in being notified about the callsite, similarly to Subscriber::register_callsite.

fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, S>) -> bool

Returns true if this layer is interested in a span or event with the given metadata in the current Context, similarly to Subscriber::enabled.

fn on_follows_from(&self, _span: &Id, _follows: &Id, _ctx: Context<'_, S>)

Notifies this layer that a span with the ID span recorded that it follows from the span with the ID follows.

fn on_id_change(&self, _old: &Id, _new: &Id, _ctx: Context<'_, S>)

Notifies this layer that a span ID has been cloned, and that the subscriber returned a different ID.

fn and_then<L>(self, layer: L) -> Layered<L, Self, S> where
    L: Layer<S>,
    Self: Sized, 

Composes this layer around the given Layer, returning a Layered struct implementing Layer.

fn with_subscriber(self, inner: S) -> Layered<Self, S> where
    Self: Sized, 

Composes this Layer with the given Subscriber, returning a Layered struct that implements Subscriber.