Struct CapturedSpan

pub struct CapturedSpan<'a> { /* private fields */ }

Captured tracing span containing a reference to its [Metadata], values that the span was created with, stats, and descendant CapturedEvents.

CapturedSpans are comparable and are partially ordered according to the capture order. Spans are considered equal iff both are aliases of the same span; i.e., equality is reference-based rather than content-based. Two spans from different Storages are not ordered and are always non-equal.

Values recorded with the span can be accessed by indexing or using Self::value(), or iterated over using Self::values().

Examples

let span: CapturedSpan = // ...
// Accessing event metadata and fields:
assert_eq!(*span.metadata().level(), Level::INFO);
assert_eq!(span["arg"], 42_u64);
assert!(span.value("other_arg").is_none());
// Filtering unsigned integer values:
let numbers = span.values().filter_map(|(_, val)| val.as_uint());

// Accessing the parent span:
let parent_name = span.parent().unwrap().metadata().name();
assert!(span
    .ancestors()
    .any(|span| span.metadata().name() == "test"));

// Accessing child spans and events:
assert!(span.children().len() > 0);
let child_messages: Vec<&str> = span
    .events()
    .filter_map(|event| event.message())
    .collect();
let descendant_span =
    span.descendants().find(|span| span["input"] == "!").unwrap();

Implementations

impl<'a> CapturedSpan<'a>

pub fn deep_scan_spans(self) -> Scanner<Self, DescendantSpans<'a>>

Deeply scans all descendants of this span.

pub fn deep_scan_events( self, ) -> Scanner<Self, impl Iterator<Item = CapturedEvent<'a>> + 'a>

Deeply scans all descendant events of this span.

impl<'a> CapturedSpan<'a>

pub fn metadata(&self) -> &'static Metadata<'static>

Provides a reference to the span metadata.

pub fn values(&self) -> impl Iterator<Item = (&'a str, &'a TracedValue)> + 'a

Iterates over values that the span was created with, or which were recorded later.

pub fn value(&self, name: &str) -> Option<&'a TracedValue>

Returns a value for the specified field, or None if the value is not defined.

pub fn stats(&self) -> SpanStats

Returns statistics about span operations.

pub fn events(&self) -> CapturedEvents<'a>

Returns events attached to this span.

pub fn parent(&self) -> Option<Self>

Returns the reference to the parent span, if any.

pub fn ancestors(&self) -> impl Iterator<Item = CapturedSpan<'a>> + '_

Returns the references to the ancestor spans, starting from the direct parent and ending in one of root spans.

pub fn children(&self) -> CapturedSpans<'a>

Iterates over the direct children of this span, in the order of their capture.

pub fn descendants(&self) -> DescendantSpans<'a>

Iterates over the descendants of this span.

In the simplest case (spans are not re-entered, span parents are contextual), the iteration order is the span capture order. In the general case, no particular order is guaranteed.

pub fn descendant_events(&self) -> DescendantEvents<'a>

Iterates over the events of the descendants of this span. The iteration order is not specified. The returned events do not include the events directly attached to this span; if you need them to be included, use something like span.events().chain(span.descendant_events()).

pub fn follows_from(&self) -> CapturedSpans<'a>

Iterates over the spans this span follows from.

Trait Implementations

impl<'a> Captured<'a> for CapturedSpan<'a>

fn metadata(&self) -> &'static Metadata<'static>

Provides a reference to the span / event metadata.

fn value(&self, name: &str) -> Option<&'a TracedValue>

Returns a value for the specified field, or None if the value is not defined.

fn parent(&self) -> Option<CapturedSpan<'a>>

Returns the reference to the parent span, if any.

impl<'a> Clone for CapturedSpan<'a>

fn clone(&self) -> CapturedSpan<'a>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for CapturedSpan<'_>

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

Formats the value using the given formatter.

impl Index<&str> for CapturedSpan<'_>

type Output = TracedValue

The returned type after indexing.

fn index(&self, index: &str) -> &Self::Output

Performs the indexing (container[index]) operation.

impl PartialEq for CapturedSpan<'_>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for CapturedSpan<'_>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<P: Predicate<str>> Predicate<CapturedSpan<'_>> for NamePredicate<P>

fn eval(&self, variable: &CapturedSpan<'_>) -> bool

Execute this Predicate against variable, returning the resulting boolean.

fn find_case( &self, expected: bool, variable: &CapturedSpan<'_>, ) -> Option<Case<'_>>

Find a case that proves this predicate as expected when run against variable.

impl<'a> ScanExt<'a> for CapturedSpan<'a>

Scans for CapturedSpan are shallow, i.e. include only direct children spans / events.

fn scan_spans(self) -> Scanner<Self, CapturedSpans<'a>>

Creates a scanner for the spans contained by this holder. What is meant by “contained” (i.e., whether the scan is deep or shallow), depends on the holder type and is documented at the corresponding impl.

fn scan_events(self) -> Scanner<Self, CapturedEvents<'a>>

Creates a scanner for the events contained by this holder. What is meant by “contained” (i.e., whether the scan is deep or shallow), depends on the holder type and is documented at the corresponding impl.

impl<'a> Copy for CapturedSpan<'a>

impl Eq for CapturedSpan<'_>