Struct SpanGuard 

pub struct SpanGuard<'a, T: Clock, P: Props, F: Completion> { /* private fields */ }

An active span in a distributed trace.

Creating active spans automatically

This type is created by the crate::span! macro with the guard control parameter, or with the crate::new_span! macro.

Call SpanGuard::complete_with, or just drop the guard to complete it, passing the resulting Span to a Completion.

Creating active spans manually

The SpanGuard::new method can be used to construct a SpanGuard and Frame manually.

Call SpanGuard::start in the closure of Frame::call or async block of Frame::in_future on the returned Frame to begin the span. Once the span is started, it will complete automatically on drop, or manually through SpanGuard::complete.

Make sure you pass ownership of the returned SpanGuard into the closure in Frame::call or async block in Frame::in_future. If you don’t, the span will complete early, without its ambient context.

Implementations

impl<'a, T: Clock, P: Props, F: Completion> SpanGuard<'a, T, P, F>

pub fn new<C: Ctxt>( filter: impl Filter, ctxt: C, clock: T, rng: impl Rng, completion: F, ctxt_props: impl Props, span_mdl: impl Into<Path<'a>>, span_name: impl Into<Str<'a>>, span_props: P, ) -> (Self, Frame<C>)

Create a new active span.

This method takes a number of parameters to construct a span. They are:

• filter, ctxt, clock, rng: These typically come from a crate::runtime::Runtime, like crate::runtime::shared.
• completion: A Completion that will be used by default when the returned SpanGuard is completed.
• ctxt_props: A set of Props that will be pushed to the ambient context.
• span_mdl, span_name, span_props: The input parameters to Span::new used to construct a span when the guard is completed.

This method constructs a span based on the input properties and current context as follows:

• A SpanCtxt for the span is generated using SpanCtxt::new_child.
• The filter is checked to see if the span should be enabled or disabled. The event passed to the filter is a Span carrying the generated span context, but without an extent.

This method returns a tuple of a SpanGuard for starting and completing the span, and a Frame carrying the generated SpanCtxt and ctxt_props.

Call SpanGuard::start in the closure of Frame::call or async block of Frame::in_future on the returned Frame to begin the span. Once the span is started, it will complete automatically on drop, or manually through SpanGuard::complete.

Make sure you pass ownership of the returned SpanGuard into the closure in Frame::call or async block in Frame::in_future. If you don’t, the span will complete early, without its ambient context.

pub fn start(&mut self)

Start the span.

From this point the span can be completed by either dropping this value, or by calling SpanGuard::complete.

pub fn is_enabled(&self) -> bool

Whether the span will call its completion.

If the filter called in SpanGuard::start evaluated to false then this method will also return false.

pub fn with_completion<U: Completion>( self, completion: U, ) -> SpanGuard<'a, T, P, U>

Set the default completion that will be called when the span is dropped or SpanGuard::complete is called.

pub fn with_mdl(self, mdl: impl Into<Path<'a>>) -> Self

Set the module of the span.

pub fn with_name(self, name: impl Into<Str<'a>>) -> Self

Set the name of the span.

pub fn with_props<U: Props>(self, props: U) -> SpanGuard<'a, T, U, F>

Set the properties of the span.

If the span is disabled then this method is a no-op.

pub fn map_props<U: Props>( self, map: impl FnOnce(P) -> U, ) -> SpanGuard<'a, T, U, F>

Map the properties of the span.

If the span is disabled then this method is a no-op.

pub fn push_prop<K: ToStr, V: ToValue>( self, key: K, value: V, ) -> SpanGuard<'a, T, And<(K, V), P>, F>

Push a property onto the span.

pub fn push_props<U: Props>(self, props: U) -> SpanGuard<'a, T, And<U, P>, F>

Push a set of properties onto the span.

pub fn props_mut(&mut self) -> Option<&mut P>

Get exclusive access to the properties of the span.

If the span is disabled this method will return None.

pub fn complete(self) -> bool

Complete the span.

If the span is disabled then this method is a no-op and will return false.

pub fn complete_with(self, completion: impl Completion) -> bool

Complete the span with the given closure.

If the span is disabled then the complete closure won’t be called and this method will return false.

Trait Implementations

impl<'a, T: Clock, P: Props, F: Completion> Drop for SpanGuard<'a, T, P, F>

fn drop(&mut self)

Executes the destructor for this type.