Struct Span

pub struct Span {}

A thread-safe span.

Implementations

impl Span

pub fn noop() -> Self

Create a place-holder span that never starts recording.

Examples

use minitrace::prelude::*;

let mut root = Span::noop();

pub fn root(name: impl Into<Cow<'static, str>>, parent: SpanContext) -> Self

Create a new trace and return its root span.

Once dropped, the root span automatically submits all associated child spans to the reporter.

Examples

use minitrace::prelude::*;

let mut root = Span::root("root", SpanContext::random());

pub fn enter_with_parent( name: impl Into<Cow<'static, str>>, parent: &Span, ) -> Self

Create a new child span associated with the specified parent span.

Examples

use minitrace::prelude::*;

let root = Span::root("root", SpanContext::random());

let child = Span::enter_with_parent("child", &root);

pub fn enter_with_parents<'a>( name: impl Into<Cow<'static, str>>, parents: impl IntoIterator<Item = &'a Span>, ) -> Self

Create a new child span associated with multiple parent spans.

This function is particularly useful when a single operation amalgamates multiple requests. It enables the creation of a unique child span that is interconnected with all the parent spans related to the requests, thereby obviating the need to generate individual child spans for each parent span.

The newly created child span, and its children, will have a replica for each trace of parent spans.

Examples

use minitrace::prelude::*;

let parent1 = Span::root("parent1", SpanContext::random());
let parent2 = Span::root("parent2", SpanContext::random());

let child = Span::enter_with_parents("child", [&parent1, &parent2]);

pub fn enter_with_local_parent(name: impl Into<Cow<'static, str>>) -> Self

Create a new child span associated with the current local span in the current thread.

If no local span is active, this function returns a no-op span.

Examples

use minitrace::prelude::*;

let root = Span::root("root", SpanContext::random());
let _g = root.set_local_parent();

let child = Span::enter_with_local_parent("child");

pub fn set_local_parent(&self) -> LocalParentGuard

Sets the current Span as the local parent for the current thread.

This method is used to establish a Span as the local parent within the current scope.

A local parent is necessary for creating a LocalSpan using LocalSpan::enter_with_local_parent(). If no local parent is set, enter_with_local_parent() will not perform any action.

Examples

use minitrace::prelude::*;

let root = Span::root("root", SpanContext::random());
let _guard = root.set_local_parent(); // root is now the local parent

// Now we can create a LocalSpan with root as the local parent.
let _span = LocalSpan::enter_with_local_parent("a child span");

pub fn with_property<K, V, F>(self, property: F) -> Self

where K: Into<Cow<'static, str>>, V: Into<Cow<'static, str>>, F: FnOnce() -> (K, V),

Add a single property to the Span and return the modified Span.

A property is an arbitrary key-value pair associated with a span.

Examples

use minitrace::prelude::*;

let root = Span::root("root", SpanContext::random()).with_property(|| ("key", "value"));

pub fn with_properties<K, V, I, F>(self, properties: F) -> Self

where K: Into<Cow<'static, str>>, V: Into<Cow<'static, str>>, I: IntoIterator<Item = (K, V)>, F: FnOnce() -> I,

Add multiple properties to the Span and return the modified Span.

Examples

use minitrace::prelude::*;

let root = Span::root("root", SpanContext::random())
    .with_properties(|| [("key1", "value1"), ("key2", "value2")]);

pub fn push_child_spans(&self, local_spans: LocalSpans)

Attach a collection of LocalSpan instances as child spans to the current span.

This method allows you to associate previously collected LocalSpan instances with the current span. This is particularly useful when the LocalSpan instances were initiated before their parent span, and were collected manually using a LocalCollector.

Examples

use minitrace::local::LocalCollector;
use minitrace::prelude::*;

// Collect local spans manually without a parent
let collector = LocalCollector::start();
let span = LocalSpan::enter_with_local_parent("a child span");
drop(span);
let local_spans = collector.collect();

// Attach the local spans to a parent
let root = Span::root("root", SpanContext::random());
root.push_child_spans(local_spans);

pub fn elapsed(&self) -> Option<Duration>

Returns the elapsed time since the span was created. If the Span is a noop span, this function will return None.

Examples

use minitrace::prelude::*;
use std::time::Duration;

let mut root = Span::root("root", SpanContext::random());

// ...

if root
    .elapsed()
    .map(|elapsed| elapsed < Duration::from_secs(1))
    .unwrap_or(false)
{
    root.cancel();
}

pub fn cancel(&mut self)

Dismisses the trace, preventing the reporting of any span records associated with it.

This is particularly useful when focusing on the tail latency of a program. For instant, you can dismiss all traces finishes within the 99th percentile.

Note

This method only dismisses the entire trace when called on the root span. If called on a non-root span, it will only cancel the reporting of that specific span.

Examples

use minitrace::prelude::*;

let mut root = Span::root("root", SpanContext::random());

root.cancel();

Trait Implementations

impl Default for Span

fn default() -> Span

Returns the “default value” for a type.

impl Drop for Span

fn drop(&mut self)

Executes the destructor for this type.