Trait Subscribe

pub trait Subscribe<C>
where
    C: Collect,
    Self: 'static,
{
    // Provided methods
    fn on_register_dispatch(&self, collector: &Dispatch) { ... }
    fn on_subscribe(&mut self, collector: &mut C) { ... }
    fn register_callsite(
        &self,
        metadata: &'static Metadata<'static>,
    ) -> Interest { ... }
    fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, C>) -> bool { ... }
    fn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, C>) { ... }
    fn on_record(&self, _span: &Id, _values: &Record<'_>, _ctx: Context<'_, C>) { ... }
    fn on_follows_from(&self, _span: &Id, _follows: &Id, _ctx: Context<'_, C>) { ... }
    fn event_enabled(&self, _event: &Event<'_>, _ctx: Context<'_, C>) -> bool { ... }
    fn on_event(&self, _event: &Event<'_>, _ctx: Context<'_, C>) { ... }
    fn on_enter(&self, _id: &Id, _ctx: Context<'_, C>) { ... }
    fn on_exit(&self, _id: &Id, _ctx: Context<'_, C>) { ... }
    fn on_close(&self, _id: Id, _ctx: Context<'_, C>) { ... }
    fn on_id_change(&self, _old: &Id, _new: &Id, _ctx: Context<'_, C>) { ... }
    fn and_then<S>(self, subscriber: S) -> Layered<S, Self, C> 
       where S: Subscribe<C>,
             Self: Sized { ... }
    fn with_collector(self, inner: C) -> Layered<Self, C> 
       where Self: Sized { ... }
    fn with_filter<F>(self, filter: F) -> Filtered<Self, F, C> 
       where Self: Sized,
             F: Filter<C> { ... }
    fn boxed(self) -> Box<dyn Subscribe<C> + Send + Sync + 'static>
       where Self: Sized + Subscribe<C> + Send + Sync + 'static,
             C: Collect { ... }
}

A composable handler for tracing events.

A type that implements Subscribe &mdash a “subscriber” — provides a particular behavior for recording or collecting traces that can be composed together with other subscribers to build a collector. See the module-level documentation for details.

Provided Methods

fn on_register_dispatch(&self, collector: &Dispatch)

Performs late initialization when installing this subscriber as a collector.

Avoiding Memory Leaks

Subscribers should not store the Dispatch pointing to the collector that they are a part of. Because the Dispatch owns the collector, storing the Dispatch within the collector will create a reference count cycle, preventing the Dispatch from ever being dropped.

Instead, when it is necessary to store a cyclical reference to the Dispatch within a subscriber, use Dispatch::downgrade to convert a Dispatch into a WeakDispatch. This type is analogous to std::sync::Weak, and does not create a reference count cycle. A WeakDispatch can be stored within a subscriber without causing a memory leak, and can be upgraded into a Dispatch temporarily when the Dispatch must be accessed by the subscriber.

fn on_subscribe(&mut self, collector: &mut C)

Performs late initialization when attaching a subscriber to a collector.

This is a callback that is called when the Subscribe is added to a Collect (e.g. in Subscribe::with_collector and CollectExt::with). Since this can only occur before the Collect has been set as the default, both the subscriber and Collect are passed to this method mutably. This gives the subscribe the opportunity to set any of its own fields with values received by method calls on the Collect.

For example, Filtered subscribers implement on_subscribe to call the Collect’s register_filter method, and store the returned FilterId as a field.

Note In most cases, subscriber implementations will not need to implement this method. However, in cases where a type implementing subscriber wraps one or more other types that implement Subscribe, like the Layered and Filtered types in this crate, that type MUST ensure that the inner Subscribe instance’s’ on_subscribe methods are called. Otherwise, unctionality that relies on on_subscribe, such as [per-subscriber filtering], may not work correctly.

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

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

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

Note: This method (and Subscribe::enabled) determine whether a span or event is
globally enabled, not whether the individual subscriber will be notified about that
span or event.  This is intended to be used by subscribers that implement filtering for
the entire stack. Subscribers 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 subscribers.

Subscribers may also implement this method to perform any behaviour that should be run once per callsite. If the subscriber 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<'_, C>) -> bool

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

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

Note: This method (and register_callsite)
determine whether a span or event is
globally enabled, not whether the individual subscriber will be
notified about that span or event. This is intended to be used
by subscribers 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 subscribers.

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

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

fn on_record(&self, _span: &Id, _values: &Record<'_>, _ctx: Context<'_, C>)

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

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

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

fn event_enabled(&self, _event: &Event<'_>, _ctx: Context<'_, C>) -> bool

Called before on_event, to determine if on_event should be called.

Note: This method determines whether an event is globally enabled,
not whether the individual subscriber will be notified about the
event. This is intended to be used by subscribers that implement
filtering for the entire stack. Subscribers which do not wish to be
notified about certain events but do not wish to globally disable them
should ignore those events in their on_event.

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

fn on_event(&self, _event: &Event<'_>, _ctx: Context<'_, C>)

Notifies this subscriber that an event has occurred.

fn on_enter(&self, _id: &Id, _ctx: Context<'_, C>)

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

fn on_exit(&self, _id: &Id, _ctx: Context<'_, C>)

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

fn on_close(&self, _id: Id, _ctx: Context<'_, C>)

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

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

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

fn and_then<S>(self, subscriber: S) -> Layered<S, Self, C>

where S: Subscribe<C>, Self: Sized,

Composes this subscriber around the given collector, returning a Layered struct implementing Subscribe.

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

pub struct FooSubscriber {
    // ...
}

pub struct BarSubscriber {
    // ...
}

pub struct MyCollector {
    // ...
}

impl<C: Collect> Subscribe<C> for FooSubscriber {
    // ...
}

impl<C: Collect> Subscribe<C> for BarSubscriber {
    // ...
}

let collector = FooSubscriber::new()
    .and_then(BarSubscriber::new())
    .with_collector(MyCollector::new());

Multiple subscribers may be composed in this manner:

pub struct BazSubscriber {
    // ...
}

impl<C: Collect> Subscribe<C> for BazSubscriber {
    // ...
}

let collector = FooSubscriber::new()
    .and_then(BarSubscriber::new())
    .and_then(BazSubscriber::new())
    .with_collector(MyCollector::new());

fn with_collector(self, inner: C) -> Layered<Self, C>

where Self: Sized,

Composes this subscriber with the given collector, returning a Layered struct that implements Collect.

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

For example:

pub struct FooSubscriber {
    // ...
}

pub struct MyCollector {
    // ...
}

impl<C: Collect> Subscribe<C> for FooSubscriber {
    // ...
}

let collector = FooSubscriber::new()
    .with_collector(MyCollector::new());

fn with_filter<F>(self, filter: F) -> Filtered<Self, F, C>

where Self: Sized, F: Filter<C>,

Available on crate features registry and std only.

Combines self with a Filter, returning a Filtered subscriber.

The Filter will control which spans and events are enabled for this subscriber. See the trait-level documentation for details on per-subscriber filtering.

fn boxed(self) -> Box<dyn Subscribe<C> + Send + Sync + 'static>

where Self: Sized + Subscribe<C> + Send + Sync + 'static, C: Collect,

Available on crate features alloc or std only.

Erases the type of this subscriber, returning a Boxed dyn Subscribe trait object.

This can be used when a function returns a subscriber which may be of one of several types, or when a composed subscriber has a very long type signature.

Examples

The following example will not compile, because the value assigned to log_subscriber may have one of several different types:

use tracing_subscriber::{Subscribe, filter::LevelFilter, prelude::*};
use std::{path::PathBuf, fs::File, io};

/// Configures whether logs are emitted to a file, to stdout, or to stderr.
pub enum LogConfig {
    File(PathBuf),
    Stdout,
    Stderr,
}

let config = // ...

// Depending on the config, construct a subscriber of one of several types.
let log_subscriber = match config {
    // If logging to a file, use a maximally-verbose configuration.
    LogConfig::File(path) => {
        let file = File::create(path)?;
        tracing_subscriber::fmt::subscriber()
            .with_thread_ids(true)
            .with_thread_names(true)
            // Selecting the JSON logging format changes the subscriber's
            // type.
            .json()
            .with_span_list(true)
            // Setting the writer to use our log file changes the
            // subscriber's type again.
            .with_writer(file)
    },

    // If logging to stdout, use a pretty, human-readable configuration.
    LogConfig::Stdout => tracing_subscriber::fmt::subscriber()
        // Selecting the "pretty" logging format changes the
        // subscriber's type!
        .pretty()
        .with_writer(io::stdout)
        // Add a filter based on the RUST_LOG environment variable;
        // this changes the type too!
        .and_then(tracing_subscriber::EnvFilter::from_default_env()),

    // If logging to stdout, only log errors and warnings.
    LogConfig::Stderr => tracing_subscriber::fmt::subscriber()
        // Changing the writer changes the subscriber's type
        .with_writer(io::stderr)
        // Only log the `WARN` and `ERROR` levels. Adding a filter
        // changes the subscriber's type to `Filtered<LevelFilter, ...>`.
        .with_filter(LevelFilter::WARN),
};

tracing_subscriber::registry()
    .with(log_subscriber)
    .init();

However, adding a call to .boxed() after each match arm erases the subscriber’s type, so this code does compile:

let log_subscriber = match config {
    LogConfig::File(path) => {
        let file = File::create(path)?;
        tracing_subscriber::fmt::subscriber()
            .with_thread_ids(true)
            .with_thread_names(true)
            .json()
            .with_span_list(true)
            .with_writer(file)
            // Erase the type by boxing the subscriber
            .boxed()
    },

    LogConfig::Stdout => tracing_subscriber::fmt::subscriber()
        .pretty()
        .with_writer(io::stdout)
        .and_then(tracing_subscriber::EnvFilter::from_default_env())
        // Erase the type by boxing the subscriber
        .boxed(),

    LogConfig::Stderr => tracing_subscriber::fmt::subscriber()
        .with_writer(io::stderr)
        .with_filter(LevelFilter::WARN)
        // Erase the type by boxing the subscriber
        .boxed(),
};

tracing_subscriber::registry()
    .with(log_subscriber)
    .init();

Trait Implementations

impl<C> Subscribe<C> for Box<dyn Subscribe<C> + Send + Sync + 'static>

where C: Collect,

Available on crate features std or alloc only.

fn on_register_dispatch(&self, collector: &Dispatch)

Performs late initialization when installing this subscriber as a collector.

fn on_subscribe(&mut self, collect: &mut C)

Performs late initialization when attaching a subscriber to a collector.

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

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

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

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

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

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

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

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

fn on_follows_from(&self, span: &Id, follows: &Id, ctx: Context<'_, C>)

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

fn event_enabled(&self, event: &Event<'_>, ctx: Context<'_, C>) -> bool

Called before on_event, to determine if on_event should be called.

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

Notifies this subscriber that an event has occurred.

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

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

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

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

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

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

fn on_id_change(&self, old: &Id, new: &Id, ctx: Context<'_, C>)

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

fn and_then<S>(self, subscriber: S) -> Layered<S, Self, C>

where S: Subscribe<C>, Self: Sized,

Composes this subscriber around the given collector, returning a Layered struct implementing Subscribe.

fn with_collector(self, inner: C) -> Layered<Self, C>

where Self: Sized,

Composes this subscriber with the given collector, returning a Layered struct that implements Collect.

fn with_filter<F>(self, filter: F) -> Filtered<Self, F, C>

where Self: Sized, F: Filter<C>,

Available on crate features registry and std only.

Combines self with a Filter, returning a Filtered subscriber.

fn boxed(self) -> Box<dyn Subscribe<C> + Send + Sync + 'static>

where Self: Sized + Subscribe<C> + Send + Sync + 'static, C: Collect,

Available on crate features alloc or std only.

Erases the type of this subscriber, returning a Boxed dyn Subscribe trait object.

Implementations on Foreign Types

impl<C> Subscribe<C> for Box<dyn Subscribe<C> + Send + Sync + 'static>

where C: Collect,

Available on crate features std or alloc only.

fn on_register_dispatch(&self, collector: &Dispatch)

fn on_subscribe(&mut self, collect: &mut C)

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

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

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

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

fn on_follows_from(&self, span: &Id, follows: &Id, ctx: Context<'_, C>)

fn event_enabled(&self, event: &Event<'_>, ctx: Context<'_, C>) -> bool

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

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

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

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

fn on_id_change(&self, old: &Id, new: &Id, ctx: Context<'_, C>)

impl<C, S> Subscribe<C> for Vec<S>

where S: Subscribe<C>, C: Collect,

Available on crate features std or alloc only.

fn on_register_dispatch(&self, collector: &Dispatch)

fn on_subscribe(&mut self, collector: &mut C)

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

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

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

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

fn on_follows_from(&self, span: &Id, follows: &Id, ctx: Context<'_, C>)

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

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

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

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

impl<S, C> Subscribe<C> for Option<S>

where S: Subscribe<C>, C: Collect,

fn on_register_dispatch(&self, collector: &Dispatch)

fn on_subscribe(&mut self, collector: &mut C)

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

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

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

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

fn on_follows_from(&self, span: &Id, follows: &Id, ctx: Context<'_, C>)

fn event_enabled(&self, event: &Event<'_>, ctx: Context<'_, C>) -> bool

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

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

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

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

fn on_id_change(&self, old: &Id, new: &Id, ctx: Context<'_, C>)

impl<S, C> Subscribe<C> for Box<S>

where S: Subscribe<C>, C: Collect,

Available on crate features std or alloc only.

fn on_register_dispatch(&self, collector: &Dispatch)

fn on_subscribe(&mut self, collect: &mut C)

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

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

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

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

fn on_follows_from(&self, span: &Id, follows: &Id, ctx: Context<'_, C>)

fn event_enabled(&self, event: &Event<'_>, ctx: Context<'_, C>) -> bool

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

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

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

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

fn on_id_change(&self, old: &Id, new: &Id, ctx: Context<'_, C>)

Implementors

impl<C> Subscribe<C> for Targets

where C: Collect,

Available on crate features std or alloc only.

impl<C, A, B> Subscribe<C> for Layered<A, B, C>

where A: Subscribe<C>, B: Subscribe<C>, C: Collect,

impl<C, F> Subscribe<C> for FilterFn<F>

where F: Fn(&Metadata<'_>) -> bool + 'static, C: Collect,

impl<C, F, R> Subscribe<C> for DynFilterFn<C, F, R>

where F: Fn(&Metadata<'_>, &Context<'_, C>) -> bool + 'static, R: Fn(&'static Metadata<'static>) -> Interest + 'static, C: Collect,

impl<C, N, E, W> Subscribe<C> for tracing_subscriber::fmt::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,

Available on crate features fmt and std only.

impl<C, S, F> Subscribe<C> for Filtered<S, F, C>

where C: Collect + for<'span> LookupSpan<'span> + 'static, F: Filter<C> + 'static, S: Subscribe<C>,

Available on crate features registry and std only.

impl<C: Collect> Subscribe<C> for EnvFilter

Available on crate features env-filter and std only.

impl<C: Collect> Subscribe<C> for LevelFilter

impl<C: Collect> Subscribe<C> for Identity

impl<S, C> Subscribe<C> for tracing_subscriber::reload::Subscriber<S>

where S: Subscribe<C> + 'static, C: Collect,

Available on crate feature std only.