[−][src]Trait opentelemetry::api::trace::tracer::Tracer

pub trait Tracer: Debug + 'static {
    type Span: Span;
    fn invalid(&self) -> Self::Span;

    fn start_from_context(&self, name: &str, context: &Context) -> Self::Span;

    fn span_builder(&self, name: &str) -> SpanBuilder;

    fn build_with_context(
        &self, 
        builder: SpanBuilder, 
        cx: &Context
    ) -> Self::Span;

    fn start(&self, name: &str) -> Self::Span { ... }

    fn build(&self, builder: SpanBuilder) -> Self::Span { ... }

#[must_use = "Dropping the guard detaches the context."]    fn mark_span_as_active(&self, span: Self::Span) -> ContextGuard { ... }

    fn get_active_span<F, T>(&self, f: F) -> T
    where
        F: FnOnce(&dyn Span) -> T,
        Self: Sized,
    { ... }

    fn in_span<T, F>(&self, name: &'static str, f: F) -> T
    where
        F: FnOnce(Context) -> T,
        Self::Span: Send + Sync,
    { ... }

    fn with_span<T, F>(&self, span: Self::Span, f: F) -> T
    where
        F: FnOnce(Context) -> T,
        Self::Span: Send + Sync,
    { ... }
}

Interface for constructing Spans.

Associated Types

type Span: Span

The Span type used by this Tracer.

Loading content...

Required methods

fn invalid(&self) -> Self::Span

Returns a span with an invalid SpanContext. Used by functions that need to return a default span like get_active_span if no span is present.

fn start_from_context(&self, name: &str, context: &Context) -> Self::Span

Starts a new Span in a given context

By default the currently active Span is set as the new Span's parent. The Tracer MAY provide other default options for newly created Spans.

Span creation MUST NOT set the newly created Span as the currently active Span by default, but this functionality MAY be offered additionally as a separate operation.

Each span has zero or one parent spans and zero or more child spans, which represent causally related operations. A tree of related spans comprises a trace. A span is said to be a root span if it does not have a parent. Each trace includes a single root span, which is the shared ancestor of all other spans in the trace. Implementations MUST provide an option to create a Span as a root span, and MUST generate a new TraceId for each root span created. For a Span with a parent, the TraceId MUST be the same as the parent. Also, the child span MUST inherit all TraceState values of its parent by default.

A Span is said to have a remote parent if it is the child of a Span created in another process. Each propagators' deserialization must set is_remote to true on a parent SpanContext so Span creation knows if the parent is remote.

fn span_builder(&self, name: &str) -> SpanBuilder

Creates a span builder

An ergonomic way for attributes to be configured before the Span is started.

fn build_with_context(&self, builder: SpanBuilder, cx: &Context) -> Self::Span

Create a span from a SpanBuilder

Loading content...

Provided methods

fn start(&self, name: &str) -> Self::Span

Starts a new Span.

By default the currently active Span is set as the new Span's parent. The Tracer MAY provide other default options for newly created Spans.

Span creation MUST NOT set the newly created Span as the currently active Span by default, but this functionality MAY be offered additionally as a separate operation.

Each span has zero or one parent spans and zero or more child spans, which represent causally related operations. A tree of related spans comprises a trace. A span is said to be a root span if it does not have a parent. Each trace includes a single root span, which is the shared ancestor of all other spans in the trace. Implementations MUST provide an option to create a Span as a root span, and MUST generate a new TraceId for each root span created. For a Span with a parent, the TraceId MUST be the same as the parent. Also, the child span MUST inherit all TraceState values of its parent by default.

A Span is said to have a remote parent if it is the child of a Span created in another process. Each propagators' deserialization must set is_remote to true on a parent SpanContext so Span creation knows if the parent is remote.

fn build(&self, builder: SpanBuilder) -> Self::Span

Create a span from a SpanBuilder

#[must_use = "Dropping the guard detaches the context."]fn mark_span_as_active(&self, span: Self::Span) -> ContextGuard

Mark a given Span as active.

The Tracer MUST provide a way to update its active Span, and MAY provide convenience methods to manage a Span's lifetime and the scope in which a Span is active. When an active Span is made inactive, the previously-active Span SHOULD be made active. A Span maybe finished (i.e. have a non-null end time) but still be active. A Span may be active on one thread after it has been made inactive on another.

Examples

use opentelemetry::{global, api::{Span, Tracer, KeyValue}};

fn my_function() {
    let tracer = global::tracer("my-component-a");
    // start an active span in one function
    let span = tracer.start("span-name");
    let _guard = tracer.mark_span_as_active(span);
    // anything happening in functions we call can still access the active span...
    my_other_function();
}

fn my_other_function() {
    // call methods on the current span from
    global::tracer("my-component-b").get_active_span(|span| {
        span.add_event("An event!".to_string(), vec![KeyValue::new("happened", true)]);
    });
}

fn get_active_span<F, T>(&self, f: F) -> T where
    F: FnOnce(&dyn Span) -> T,
    Self: Sized, 

Executes a closure with a reference to this thread's current span.

Examples

use opentelemetry::{global, api::{Span, Tracer, KeyValue}};

fn my_function() {
    // start an active span in one function
    global::tracer("my-component").in_span("span-name", |_cx| {
        // anything happening in functions we call can still access the active span...
        my_other_function();
    })
}

fn my_other_function() {
    // call methods on the current span from
    global::tracer("my-component").get_active_span(|span| {
        span.add_event("An event!".to_string(), vec![KeyValue::new("happened", true)]);
    })
}

fn in_span<T, F>(&self, name: &'static str, f: F) -> T where
    F: FnOnce(Context) -> T,
    Self::Span: Send + Sync, 

Start a new span and execute the given closure with reference to the span's context.

This method starts a new span and sets it as the active span for the given function. It then executes the body. It closes the span before returning the execution result.

Examples

use opentelemetry::{global, api::{Span, Tracer, KeyValue}};

fn my_function() {
    // start an active span in one function
    global::tracer("my-component").in_span("span-name", |_cx| {
        // anything happening in functions we call can still access the active span...
        my_other_function();
    })
}

fn my_other_function() {
    // call methods on the current span from
    global::tracer("my-component").get_active_span(|span| {
        span.add_event("An event!".to_string(), vec![KeyValue::new("happened", true)]);
    })
}

fn with_span<T, F>(&self, span: Self::Span, f: F) -> T where
    F: FnOnce(Context) -> T,
    Self::Span: Send + Sync, 

Start a new span and execute the given closure with reference to the span's context.

This method starts a new span and sets it as the active span for the given function. It then executes the body. It closes the span before returning the execution result.

Examples

use opentelemetry::{global, api::{Span, SpanKind, Tracer, KeyValue}};

fn my_function() {
    let tracer = global::tracer("my-component");
    // start a span with custom attributes via span bulder
    let span = tracer.span_builder("span-name").with_kind(SpanKind::Server).start(&tracer);
    // Mark the span as active for the duration of the closure
    global::tracer("my-component").with_span(span, |_cx| {
        // anything happening in functions we call can still access the active span...
        my_other_function();
    })
}

fn my_other_function() {
    // call methods on the current span from
    global::tracer("my-component").get_active_span(|span| {
        span.add_event("An event!".to_string(), vec![KeyValue::new("happened", true)]);
    })
}
Loading content...

Implementors

impl Tracer for NoopTracer[src]

type Span = NoopSpan

fn invalid(&self) -> Self::Span[src]

Returns a NoopSpan as they are always invalid.

fn start_from_context(&self, _name: &str, _context: &Context) -> Self::Span[src]

Starts a new NoopSpan.

fn span_builder(&self, name: &str) -> SpanBuilder[src]

Starts a SpanBuilder

fn build_with_context(&self, _builder: SpanBuilder, _cx: &Context) -> Self::Span[src]

Builds a NoopSpan from a SpanBuilder

impl Tracer for BoxedTracer[src]

type Span = BoxedSpan

Global tracer uses BoxedSpans so that it can be a global singleton, which is not possible if it takes generic type parameters.

fn invalid(&self) -> Self::Span[src]

Returns a span with an inactive SpanContext. Used by functions that need to return a default span like get_active_span if no span is present.

fn start_from_context(&self, name: &str, cx: &Context) -> Self::Span[src]

Starts a new Span.

Each span has zero or one parent spans and zero or more child spans, which represent causally related operations. A tree of related spans comprises a trace. A span is said to be a root span if it does not have a parent. Each trace includes a single root span, which is the shared ancestor of all other spans in the trace.

fn span_builder(&self, name: &str) -> SpanBuilder[src]

Creates a span builder

An ergonomic way for attributes to be configured before the Span is started.

fn build_with_context(&self, builder: SpanBuilder, cx: &Context) -> Self::Span[src]

Create a span from a SpanBuilder

impl Tracer for Tracer[src]

type Span = Span

This implementation of api::Tracer produces sdk::Span instances.

fn invalid(&self) -> Self::Span[src]

Returns a span with an inactive SpanContext. Used by functions that need to return a default span like get_active_span if no span is present.

fn start_from_context(&self, name: &str, cx: &Context) -> Self::Span[src]

Starts a new Span in a given context.

Each span has zero or one parent spans and zero or more child spans, which represent causally related operations. A tree of related spans comprises a trace. A span is said to be a root span if it does not have a parent. Each trace includes a single root span, which is the shared ancestor of all other spans in the trace.

fn span_builder(&self, name: &str) -> SpanBuilder[src]

Creates a span builder

An ergonomic way for attributes to be configured before the Span is started.

fn build_with_context(&self, builder: SpanBuilder, cx: &Context) -> Self::Span[src]

Starts a span from a SpanBuilder.

Each span has zero or one parent spans and zero or more child spans, which represent causally related operations. A tree of related spans comprises a trace. A span is said to be a root span if it does not have a parent. Each trace includes a single root span, which is the shared ancestor of all other spans in the trace.

Loading content...