🛈 Note: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem.

For the release documentation, please see docs.rs, instead.

Trait tracing_subscriber::subscribe::Subscribe

source ·
pub trait Subscribe<C>
where C: Collect, Self: 'static,
{
Show 17 methods // 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 { ... }
}
Expand description

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§

source

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.

source

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.

source

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().

source

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.

source

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.

source

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.

source

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.

source

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.

source

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

Notifies this subscriber that an event has occurred.

source

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

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

source

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

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

source

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

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

source

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.

source

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());
source

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());
source

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.

source

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§

source§

impl<C> Subscribe<C> for Box<dyn Subscribe<C> + Send + Sync + 'static>
where C: Collect,

Available on crate features std or alloc only.
source§

fn on_register_dispatch(&self, collector: &Dispatch)

Performs late initialization when installing this subscriber as a collector. Read more
source§

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

Performs late initialization when attaching a subscriber to a collector. Read more
source§

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. Read more
source§

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.
source§

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. Read more
source§

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.
source§

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.
source§

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

Called before on_event, to determine if on_event should be called. Read more
source§

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

Notifies this subscriber that an event has occurred.
source§

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

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

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

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

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

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

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.
source§

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. Read more
source§

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. Read more
source§

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. Read more
source§

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. Read more

Implementations on Foreign Types§

source§

impl<C> Subscribe<C> for Box<dyn Subscribe<C> + Send + Sync + 'static>
where C: Collect,

Available on crate features std or alloc only.
source§

fn on_register_dispatch(&self, collector: &Dispatch)

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

impl<C, S> Subscribe<C> for Vec<S>
where S: Subscribe<C>, C: Collect,

Available on crate features std or alloc only.
source§

fn on_register_dispatch(&self, collector: &Dispatch)

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

impl<S, C> Subscribe<C> for Option<S>
where S: Subscribe<C>, C: Collect,

source§

fn on_register_dispatch(&self, collector: &Dispatch)

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

impl<S, C> Subscribe<C> for Box<S>
where S: Subscribe<C>, C: Collect,

Available on crate features std or alloc only.
source§

fn on_register_dispatch(&self, collector: &Dispatch)

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

Implementors§

source§

impl<C> Subscribe<C> for Targets
where C: Collect,

Available on crate features std or alloc only.
source§

impl<C, A, B> Subscribe<C> for Layered<A, B, C>
where A: Subscribe<C>, B: Subscribe<C>, C: Collect,

source§

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

source§

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,

source§

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.
source§

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.
source§

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

Available on crate features env-filter and std only.
source§

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

source§

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

source§

impl<S, C> Subscribe<C> for tracing_subscriber::reload::Subscriber<S>
where S: Subscribe<C> + 'static, C: Collect,

Available on crate feature std only.