[−][src]Trait tracing_subscriber::layer::Layer

pub trait Layer<S> where
    S: Subscriber,
    Self: 'static, {
    fn register_callsite(
        &self, 
        metadata: &'static Metadata<'static>
    ) -> Interest { ... }

    fn enabled(&self, metadata: &Metadata, ctx: Context<S>) -> bool { ... }

    fn new_span(&self, attrs: &Attributes, id: &Id, ctx: Context<S>) { ... }

    fn on_record(&self, _span: &Id, _values: &Record, _ctx: Context<S>) { ... }

    fn on_follows_from(&self, _span: &Id, _follows: &Id, _ctx: Context<S>) { ... }

    fn on_event(&self, _event: &Event, _ctx: Context<S>) { ... }

    fn on_enter(&self, _id: &Id, _ctx: Context<S>) { ... }

    fn on_exit(&self, _id: &Id, _ctx: Context<S>) { ... }

    fn on_close(&self, _id: Id, _ctx: Context<S>) { ... }

    fn on_id_change(&self, _old: &Id, _new: &Id, _ctx: Context<S>) { ... }

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

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

A composable handler for tracing events.

The Subscriber trait in tracing-core represents the complete set of functionality required to consume tracing instrumentation. This means that a single Subscriber instance is a self-contained implementation of a complete strategy for collecting traces; but it also means that the Subscriber trait cannot easily be composed with other Subscribers.

In particular, Subscriber's are responsible for generating span IDs and assigning them to spans. Since these IDs must uniquely identify a span within the context of the current trace, this means that there may only be a single Subscriber for a given thread at any point in time — otherwise, there would be no authoritative source of span IDs.

On the other hand, the majority of the Subscriber trait's functionality is composable: any number of subscribers may observe events, span entry and exit, and so on, provided that there is a single authoritative source of span IDs. The Layer trait represents this composable subset of the Subscriber behavior; it can observe events and spans, but does not assign IDs.

Recording Traces

The Layer trait defines a set of methods for consuming notifications from tracing instrumentation, which are generally equivalent to the similarly named methods on Subscriber. Unlike Subscriber, the methods on Layer are additionally passed a Context type, which exposes additional information provided by the wrapped subscriber (such as the current span) to the layer.

Filtering with Layers

As well as strategies for handling trace events, the Layer trait may also be used to represent composable filters. This allows the determination of what spans and events should be recorded to be decoupled from how they are recorded: a filtering layer can be applied to other layers or subscribers. A Layer that implements a filtering strategy should override the register_callsite and/or enabled methods. It may also choose to implement methods such as on_enter, if it wishes to filter trace events based on the current span context.

Note that the Layer::register_callsite and Layer::enabled methods determine whether a span or event is enabled globally. Thus, they should not be used to indicate whether an individual layer wishes to record a particular span or event. Instead, if a layer is only interested in a subset of trace data, but does not wish to disable other spans and events for the rest of the layer stack should ignore those spans and events in its notification methods.

The filtering methods on a stack of Layers are evaluated in a top-down order, starting with the outermost Layer and ending with the wrapped Subscriber. If any layer returns false from its enabled method, or Interest::never() from its register_callsite method, filter evaluation will short-circuit and the span or event will be disabled.

Provided methods

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.

By default, this returns Interest::always() if self.enabled returns true, or Interest::never() if it returns false.

Note: This method (and Layer::enabled) determine whether a span or event is globally enabled, not whether the individual layer will be notified about that span or event. This is intended to be used by layers that implement filtering for the entire stack. Layers which do not wish to be notified about certain spans or events but do not wish to globally disable them should ignore those spans or events in their on_event, on_enter, on_exit, and other notification methods.

See the trait-level documentation for more information on filtering with Layers.

Layers may also implement this method to perform any behaviour that should be run once per callsite. If the layer wishes to use register_callsite for per-callsite behaviour, but does not want to globally enable or disable those callsites, it should always return Interest::always().

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.

By default, this always returns true, allowing the wrapped subscriber to choose to disable the span.

Note: This method (and Layer::register_callsite) determine whether a span or event is globally enabled, not whether the individual layer will be notified about that span or event. This is intended to be used by layers that implement filtering for the entire stack. Layers which do not wish to be notified about certain spans or events but do not wish to globally disable them should ignore those spans or events in their on_event, on_enter, on_exit, and other notification methods.

See the trait-level documentation for more information on filtering with Layers.

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, _span: &Id, _values: &Record, _ctx: Context<S>)

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

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_event(&self, _event: &Event, _ctx: Context<S>)

Notifies this layer that an event has occurred.

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_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.

The returned Layer will call the methods on this Layer and then those of the new Layer, before calling the methods on the subscriber it wraps. For example:

pub struct FooLayer {
    // ...
}

pub struct BarLayer {
    // ...
}

pub struct MySubscriber {
    // ...
}

impl<S: Subscriber> Layer<S> for FooLayer {
    // ...
}

impl<S: Subscriber> Layer<S> for BarLayer {
    // ...
}

let subscriber = FooLayer::new()
    .and_then(BarLayer::new())
    .with_subscriber(MySubscriber::new());

Multiple layers may be composed in this manner:

pub struct BazLayer {
    // ...
}

impl<S: Subscriber> Layer<S> for BazLayer {
    // ...
}

let subscriber = FooLayer::new()
    .and_then(BarLayer::new())
    .and_then(BazLayer::new())
    .with_subscriber(MySubscriber::new());

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.

The returned Layered subscriber will call the methods on this Layer and then those of the wrapped subscriber.

For example:

pub struct FooLayer {
    // ...
}

pub struct MySubscriber {
    // ...
}

impl<S: Subscriber> Layer<S> for FooLayer {
    // ...
}

let subscriber = FooLayer::new()
    .with_subscriber(MySubscriber::new());
Loading content...

Implementors

impl<L, S> Layer<S> for tracing_subscriber::reload::Layer<L, S> where
    L: Layer<S> + 'static,
    S: Subscriber, [src]

impl<S, A, B> Layer<S> for Layered<A, B, S> where
    A: Layer<S>,
    B: Layer<S>,
    S: Subscriber, [src]

impl<S, N, E, W> Layer<S> for tracing_subscriber::fmt::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, [src]

impl<S: Subscriber> Layer<S> for EnvFilter[src]

impl<S: Subscriber> Layer<S> for LevelFilter[src]

impl<S: Subscriber> Layer<S> for Identity[src]

Loading content...