Struct tracing_subscriber::layer::Context

source ·
pub struct Context<'a, S> { /* private fields */ }
Expand description

Represents information about the current context provided to Layers by the wrapped Subscriber.

To access stored data keyed by a span ID, implementors of the Layer trait should ensure that the Subscriber type parameter is also bound by the LookupSpan:

use tracing::Subscriber;
use tracing_subscriber::{Layer, registry::LookupSpan};

pub struct MyLayer;

impl<S> Layer<S> for MyLayer
where
    S: Subscriber + for<'a> LookupSpan<'a>,
{
    // ...
}

Implementations§

source§

impl<'a, S> Context<'a, S>
where S: Subscriber,

source

pub fn current_span(&self) -> Current

Returns the wrapped subscriber’s view of the current span.

source

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

Returns whether the wrapped subscriber would enable the current span.

source

pub fn event(&self, event: &Event<'_>)

Records the provided event with the wrapped subscriber.

§Notes
  • The subscriber is free to expect that the event’s callsite has been registered, and may panic or fail to observe the event if this is not the case. The tracing crate’s macros ensure that all events are registered, but if the event is constructed through other means, the user is responsible for ensuring that register_callsite has been called prior to calling this method.
  • This does not call enabled on the inner subscriber. If the caller wishes to apply the wrapped subscriber’s filter before choosing whether to record the event, it may first call Context::enabled to check whether the event would be enabled. This allows Layers to elide constructing the event if it would not be recorded.
source

pub fn event_span(&self, event: &Event<'_>) -> Option<SpanRef<'_, S>>
where S: for<'lookup> LookupSpan<'lookup>,

Returns a SpanRef for the parent span of the given Event, if it has a parent.

If the event has an explicitly overridden parent, this method returns a reference to that span. If the event’s parent is the current span, this returns a reference to the current span, if there is one. If this returns None, then either the event’s parent was explicitly set to None, or the event’s parent was defined contextually, but no span is currently entered.

Compared to Context::current_span and Context::lookup_current, this respects overrides provided by the Event.

Compared to Event::parent, this automatically falls back to the contextual span, if required.

use tracing::{Event, Subscriber};
use tracing_subscriber::{
    layer::{Context, Layer},
    prelude::*,
    registry::LookupSpan,
};

struct PrintingLayer;
impl<S> Layer<S> for PrintingLayer
where
    S: Subscriber + for<'lookup> LookupSpan<'lookup>,
{
    fn on_event(&self, event: &Event, ctx: Context<S>) {
        let span = ctx.event_span(event);
        println!("Event in span: {:?}", span.map(|s| s.name()));
    }
}

tracing::subscriber::with_default(tracing_subscriber::registry().with(PrintingLayer), || {
    tracing::info!("no span");
    // Prints: Event in span: None

    let span = tracing::info_span!("span");
    tracing::info!(parent: &span, "explicitly specified");
    // Prints: Event in span: Some("span")

    let _guard = span.enter();
    tracing::info!("contextual span");
    // Prints: Event in span: Some("span")
});
    Note: This requires the wrapped subscriber to
    implement the 
    LookupSpan trait. See the documentation on
    Context's
    declaration for details.
source

pub fn metadata(&self, id: &Id) -> Option<&'static Metadata<'static>>
where S: for<'lookup> LookupSpan<'lookup>,

Returns metadata for the span with the given id, if it exists.

If this returns None, then no span exists for that ID (either it has closed or the ID is invalid).

source

pub fn span(&self, id: &Id) -> Option<SpanRef<'_, S>>
where S: for<'lookup> LookupSpan<'lookup>,

Returns stored data for the span with the given id, if it exists.

If this returns None, then no span exists for that ID (either it has closed or the ID is invalid).

    Note: This requires the wrapped subscriber to
    implement the 
    LookupSpan trait. See the documentation on
    Context's
    declaration for details.
source

pub fn exists(&self, id: &Id) -> bool
where S: for<'lookup> LookupSpan<'lookup>,

Returns true if an active span exists for the given Id.

    Note: This requires the wrapped subscriber to
    implement the 
    LookupSpan trait. See the documentation on
    Context's
    declaration for details.
source

pub fn lookup_current(&self) -> Option<SpanRef<'_, S>>
where S: for<'lookup> LookupSpan<'lookup>,

Returns stored data for the span that the wrapped subscriber considers to be the current.

If this returns None, then we are not currently within a span.

    Note: This requires the wrapped subscriber to
    implement the 
    LookupSpan trait. See the documentation on
    Context's
    declaration for details.
source

pub fn span_scope(&self, id: &Id) -> Option<Scope<'_, S>>
where S: for<'lookup> LookupSpan<'lookup>,

Returns an iterator over the stored data for all the spans in the current context, starting with the specified span and ending with the root of the trace tree and ending with the current span.

Note: Compared to scope this
returns the spans in reverse order (from leaf to root). Use
Scope::from_root
in case root-to-leaf ordering is desired.
    Note: This requires the wrapped subscriber to
    implement the 
    LookupSpan trait. See the documentation on
    Context's
    declaration for details.
source

pub fn event_scope(&self, event: &Event<'_>) -> Option<Scope<'_, S>>
where S: for<'lookup> LookupSpan<'lookup>,

Returns an iterator over the stored data for all the spans in the current context, starting with the parent span of the specified event, and ending with the root of the trace tree and ending with the current span.

Note: Compared to scope this
returns the spans in reverse order (from leaf to root). Use
Scope::from_root
in case root-to-leaf ordering is desired.
    Note: This requires the wrapped subscriber to
    implement the 
    LookupSpan trait. See the documentation on
    Context's
    declaration for details.

Trait Implementations§

source§

impl<'a, S> Clone for Context<'a, S>

source§

fn clone(&self) -> Self

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl<'a, S: Debug> Debug for Context<'a, S>

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<'a, S> Freeze for Context<'a, S>

§

impl<'a, S> RefUnwindSafe for Context<'a, S>
where S: RefUnwindSafe,

§

impl<'a, S> Send for Context<'a, S>
where S: Sync,

§

impl<'a, S> Sync for Context<'a, S>
where S: Sync,

§

impl<'a, S> Unpin for Context<'a, S>

§

impl<'a, S> UnwindSafe for Context<'a, S>
where S: RefUnwindSafe,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more