[−][src]Trait opentelemetry::api::trace::Tracer
Interface for constructing Span
s.
Associated Types
Loading content...Required methods
fn invalid(&self) -> Self::Span
Returns a span with an invalid SpanReference
. 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 Span
s.
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 SpanReference
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
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 Span
s.
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 SpanReference
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::{trace::{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,
F: FnOnce(&dyn Span) -> T,
Self: Sized,
Executes a closure with a reference to this thread's current span.
Examples
use opentelemetry::{global, api::{trace::{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,
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::{trace::{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,
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::{trace::{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)]); }) }
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, cx: &Context) -> Self::Span
[src]
Starts a new NoopSpan
in a given context.
If the context contains a valid span context, it is progagated.
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
.
If the span builder or context contains a valid span context, it is progagated.
impl Tracer for Tracer
[src]
type Span = Span
This implementation of api::trace::Tracer
produces sdk::Span
instances.
fn invalid(&self) -> Self::Span
[src]
Returns a span with an inactive SpanReference
. 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.