Constructs a newSpan with the givenmetadata and set offield values.

The new span will be constructed by the currently-activeSubscriber,with the current span as its parent (if one exists).

After the span is constructed,field values and/orfollows_fromannotations may be added to it.

Constructs a newSpan as the root of its own trace tree, with thegivenmetadata and set offield values.

After the span is constructed,field values and/orfollows_fromannotations may be added to it.

Constructs a newSpan as child of the given parent span, with thegivenmetadata and set offield values.

After the span is constructed,field values and/orfollows_fromannotations may be added to it.

Constructs a new disabled span with the givenMetadata.

This should be used when a span is constructed from a known callsite,but the subscriber indicates that it is disabled.

Entering, exiting, and recording values on this span will not notify theSubscriber butmay record log messages if thelog feature flag isenabled.

Constructs a new span that iscompletely disabled.

This can be used rather thanOption<Span> to represent cases where aspan is not present.

Entering, exiting, and recording values on this span will do nothing.

Returns a handle to the spanconsidered by theSubscriber to be thecurrent span.

If the subscriber indicates that it does not track the current span, orthat the thread from which this function is called is not currentlyinside a span, the returned span will be disabled.

Enters this span, returning a guard that will exit the span when dropped.

If this span is enabled by the current subscriber, then this function willcallSubscriber::enter with the span’sId, and dropping the guardwill callSubscriber::exit. If the span is disabled, this doesnothing.

§In Asynchronous Code

Warning: in asynchronous code that usesasync/await syntax,Span::enter should be used very carefully or avoided entirely. Holdingthe drop guard returned bySpan::enter across.await points willresult in incorrect traces. For example,

async fnmy_async_function() {letspan =info_span!("my_async_function");// WARNING: This span will remain entered until this    // guard is dropped...let_enter = span.enter();// ...but the `await` keyword may yield, causing the    // runtime to switch to another task, while remaining in    // this span!some_other_async_function().await// ...}

The drop guard returned bySpan::enter exits the span when it isdropped. When an async function or async block yields at an.awaitpoint, the current scope isexited, but values in that scope arenot dropped (because the async block will eventually resumeexecution from that await point). This means thatanother task willbegin executing whileremaining in the entered span. This results inan incorrect trace.

Instead of usingSpan::enter in asynchronous code, prefer thefollowing:

• To enter a span for a synchronous section of code within an asyncblock or function, preferSpan::in_scope. Sincein_scope takes asynchronous closure and exits the span when the closure returns, thespan will always be exited before the next await point. For example:

  async fnmy_async_function() {letspan =info_span!("my_async_function");letsome_value = span.in_scope(|| {// run some synchronous code inside the span...});// This is okay! The span has already been exited before we reach    // the await point.some_other_async_function(some_value).await;// ...}

• For instrumenting asynchronous code,tracing provides theFuture::instrument combinator forattaching a span to a future (async function or block). This willenter the spanevery time the future is polled, and exit it wheneverthe future yields.

  Instrument can be used with an async block inside an async function:

  ⓘ

  usetracing::Instrument;async fnmy_async_function() {letspan =info_span!("my_async_function");async move{// This is correct! If we yield here, the span will be exited,       // and re-entered when we resume.some_other_async_function().await;//more asynchronous code inside the span...}// instrument the async block with the span....instrument(span)// ...and await it..await}

  It can also be used to instrument calls to async functions at thecallsite:

  ⓘ

  usetracing::Instrument;async fnmy_async_function() {letsome_value = some_other_async_function()       .instrument(debug_span!("some_other_async_function"))       .await;// ...}

• The#[instrument] attribute macro can automatically generatecorrect code when used on an async function:

  ⓘ

  #[tracing::instrument(level ="info")]async fnmy_async_function() {// This is correct! If we yield here, the span will be exited,    // and re-entered when we resume.some_other_async_function().await;// ...}

§Examples

letspan =span!(Level::INFO,"my_span");letguard = span.enter();// code here is within the spandrop(guard);// code here is no longer within the span

Guards need not be explicitly dropped:

fnmy_function() -> String {// enter a span for the duration of this function.letspan =trace_span!("my_function");let_enter = span.enter();// anything happening in functions we call is still inside the span...my_other_function();// returning from the function drops the guard, exiting the span.return"Hello world".to_owned();}fnmy_other_function() {// ...}

Sub-scopes may be created to limit the duration for which the span isentered:

letspan =info_span!("my_great_span");{let_enter = span.enter();// this event occurs inside the span.info!("i'm in the span!");// exiting the scope drops the guard, exiting the span.}// this event is not inside the span.info!("i'm outside the span!")

Enters this span, consuming it and returning aguardthat will exit the span when dropped.

Warning: In asynchronous code that uses async/await syntax,Span::entered may produce incorrect traces if the returned drop    guard is held across an await point. SeetheSpan::enter documentation for details.

If this span is enabled by the current subscriber, then this function willcallSubscriber::enter with the span’sId, and dropping the guardwill callSubscriber::exit. If the span is disabled, this doesnothing.

This is similar to theSpan::enter method, except that it moves thespan by value into the returned guard, rather than borrowing it.Therefore, this method can be used to create and enter a span in asingle expression, without requiring alet-binding. For example:

let_span =info_span!("something_interesting").entered();

rather than:

letspan =info_span!("something_interesting");let_e = span.enter();

Furthermore,entered may be used when the span must be stored in someother struct or be passed to a function while remaining entered.

Note: The returnedEnteredSpan guard does not implementSend.    Dropping the guard will exitthis span, and if the guard is sent    to another thread and dropped there, that thread may never have entered    this span. Thus,EnteredSpans should not be sent between threads.

§Examples

The returned guard can beexplicitly exited,returning the un-entered span:

letspan =span!(Level::INFO,"doing_something").entered();// code here is within the span// explicitly exit the span, returning itletspan = span.exit();// code here is no longer within the span// enter the span againletspan = span.entered();// now we are inside the span once again

Guards need not be explicitly dropped:

fnmy_function() -> String {// enter a span for the duration of this function.letspan =trace_span!("my_function").entered();// anything happening in functions we call is still inside the span...my_other_function();// returning from the function drops the guard, exiting the span.return"Hello world".to_owned();}fnmy_other_function() {// ...}

Since theEnteredSpan guard can dereference to theSpan itself,the span may still be accessed while entered. For example:

usetracing::field;// create the span with an empty field, and enter it.letspan =info_span!("my_span", some_field = field::Empty).entered();// we can still record a value for the field while the span is entered.span.record("some_field",&"hello world!");

Returns this span, if it wasenabled by the currentSubscriber, orthecurrent span (whose lexical distance may be further than expected),if this spanis disabled.

This method can be useful when propagating spans to spawned threads orasync tasks. Consider the following:

let_parent_span =tracing::info_span!("parent").entered();// ...letchild_span =tracing::debug_span!("child");std::thread::spawn(move|| {let_entered = child_span.entered();tracing::info!("spawned a thread!");// ...});

If the currentSubscriber enables theDEBUG level, then boththe “parent” and “child” spans will be enabled. Thus, when the “spawaneda thread!” event occurs, it will be inside of the “child” span. Because“parent” is the parent of “child”, the event willalso be inside of“parent”.

However, if theSubscriber only enables theINFO level, the “child”span will be disabled. When the thread is spawned, thechild_span.entered() call will do nothing, since “child” is notenabled. In this case, the “spawned a thread!” event occurs outside ofany span, since the “child” span was responsible for propagating itsparent to the spawned thread.

If this is not the desired behavior,Span::or_current can be used toensure that the “parent” span is propagated in both cases, either as aparent of “child”or directly. For example:

let_parent_span =tracing::info_span!("parent").entered();// ...// If DEBUG is enabled, then "child" will be enabled, and `or_current`// returns "child". Otherwise, if DEBUG is not enabled, "child" will be// disabled, and `or_current` returns "parent".letchild_span =tracing::debug_span!("child").or_current();std::thread::spawn(move|| {let_entered = child_span.entered();tracing::info!("spawned a thread!");// ...});

When spawningasynchronous tasks,Span::or_current canbe used similarly, in combination withinstrument:

usetracing::Instrument;let_parent_span =tracing::info_span!("parent").entered();// ...letchild_span =tracing::debug_span!("child");tokio::spawn(async{tracing::info!("spawned a task!");// ...}.instrument(child_span.or_current()));

In general,or_current should be preferred over nesting aninstrument call inside of anin_current_span call, as usingor_current will be more efficient.

usetracing::Instrument;async fnmy_async_fn() {// ...}let_parent_span =tracing::info_span!("parent").entered();// Do this:tokio::spawn(    my_async_fn().instrument(tracing::debug_span!("child").or_current()));// ...rather than this:tokio::spawn(    my_async_fn()        .instrument(tracing::debug_span!("child"))        .in_current_span());

Executes the given function in the context of this span.

If this span is enabled, then this function enters the span, invokesfand then exits the span. If the span is disabled,f will still beinvoked, but in the context of the currently-executing span (if there isone).

Returns the result of evaluatingf.

§Examples

letmy_span =span!(Level::TRACE,"my_span");my_span.in_scope(|| {// this event occurs within the span.trace!("i'm in the span!");});// this event occurs outside the span.trace!("i'm not in the span!");

Calling a function and returning the result:

fnhello_world() -> String {"Hello world!".to_owned()}letspan =info_span!("hello_world");// the span will be entered for the duration of the call to// `hello_world`.leta_string = span.in_scope(hello_world);

Returns aField for the field with thegivenname, if one exists,

Returns true if thisSpan has a field for the givenField or field name.

Records that the field described byfield has the valuevalue.

This may be used withfield::Empty to declare fields whose valuesare not known when the span is created, and record them later:

usetracing::{trace_span, field};// Create a span with two fields: `greeting`, with the value "hello world", and// `parting`, without a value.letspan =trace_span!("my_span", greeting ="hello world", parting = field::Empty);// ...// Now, record a value for parting as well.// (note that the field name is passed as a string slice)span.record("parting","goodbye world!");

However, it may also be used to record anew value for a field whosevalue was already recorded:

usetracing::info_span;// Initially, let's assume that our attempt to do something is going okay...letspan =info_span!("doing_something", is_okay =true);let_e = span.enter();matchdo_something() {Ok(something) => {// ...}Err(_) => {// Things are no longer okay!span.record("is_okay",false);    }}

Note: The fields associated with a span are part    of itsMetadata.    TheMetadata    describing a particular span is constructed statically when the span    is created and cannot be extended later to add new fields. Therefore,    you cannot record a value for a field that was not specified when the    span was created:

usetracing::{trace_span, field};// Create a span with two fields: `greeting`, with the value "hello world", and// `parting`, without a value.letspan =trace_span!("my_span", greeting ="hello world", parting = field::Empty);// ...// Now, you try to record a value for a new field, `new_field`, which was not// declared as `Empty` or populated when you created `span`.// You won't get any error, but the assignment will have no effect!span.record("new_field","interesting_value_you_really_need");// Instead, all fields that may be recorded after span creation should be declared up front,// using field::Empty when a value is not known, as we did for `parting`.// This `record` call will indeed replace field::Empty with "you will be remembered".span.record("parting","you will be remembered");

Records all the fields in the providedValueSet.

Returnstrue if this span was disabled by the subscriber and does notexist.

See alsois_none.

Returnstrue if this span was constructed bySpan::none and isempty.

Ifis_none returnstrue for a given span, thenis_disabled willalso returntrue. However, when a span is disabled by the subscriberrather than constructed bySpan::none, this method will returnfalse, whileis_disabled will returntrue.

Indicates that the span with the given ID has an indirect causalrelationship with this span.

This relationship differs somewhat from the parent-child relationship: aspan may have any number of prior spans, rather than a single one; andspans are not considered to be executinginside of the spans theyfollow from. This means that a span may close even if subsequent spansthat follow from it are still open, and time spent inside of asubsequent span should not be included in the time its precedents wereexecuting. This is used to model causal relationships such as when asingle future spawns several related background tasks, et cetera.

If this span is disabled, or the resulting follows-from relationshipwould be invalid, this function will do nothing.

§Examples

Setting afollows_from relationship with aSpan:

letspan1 =span!(Level::INFO,"span_1");letspan2 =span!(Level::DEBUG,"span_2");span2.follows_from(span1);

Setting afollows_from relationship with the current span:

letspan =span!(Level::INFO,"hello!");span.follows_from(Span::current());

Setting afollows_from relationship with aSpan reference:

letspan =span!(Level::INFO,"hello!");letcurr = Span::current();span.follows_from(&curr);

Setting afollows_from relationship with anId:

letspan =span!(Level::INFO,"hello!");letid = span.id();span.follows_from(id);

Returns this span’sId, if it is enabled.

Returns this span’sMetadata, if it is enabled.

Invokes a function with a reference to this span’s ID and subscriber.

if this span is enabled, the provided function is called, and the result is returned.If the span is disabled, the function is not called, and this method returnsNoneinstead.

Returns the argument unchanged.

CallsU::from(self).

That is, this conversion is whatever the implementation ofFrom<T> for U chooses to do.