# tracing::span::EnteredSpan - Rust
API documentation for the Rust `EnteredSpan` struct in crate `tracing`.
Keywords: rust, rustlang, rust-lang, EnteredSpan

# Struct tracing::span::EnteredSpan [−] [src]

    #[must_use = "once a span has been entered, it should be exited"]pub struct EnteredSpan { /* fields omitted */ }

An owned version of `Entered`, a guard representing a span which has been entered and is currently executing.

When the guard is dropped, the span will be exited.

This is returned by the `Span::entered` function.

## Implementations

### `impl EnteredSpan` [src]

#### `pub fn exit(self) -> Span` [src]

Exits this span, returning the underlying `Span`.

## Methods from Deref<Target = Span>

#### `pub fn enter(&self) -> Entered<'_>` [src]

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 will call `Subscriber::enter` with the span's `Id`, and dropping the guard will call `Subscriber::exit`. If the span is disabled, this does nothing.

# In Asynchronous Code

Warning: in asynchronous code that uses async/await syntax, `Span::enter` should be used very carefully or avoided entirely. Holding the drop guard returned by `Span::enter` across `.await` points will result in incorrect traces.

For example,

    async fn my_async_function() {
        let span = info_span!("my_async_function");

        // THIS WILL RESULT IN INCORRECT TRACES
        let _enter = span.enter();
        some_other_async_function().await;

        // ...
    }

The drop guard returned by `Span::enter` exits the span when it is dropped. When an async function or async block yields at an `.await` point, the current scope is exited, but values in that scope are not dropped (because the async block will eventually resume execution from that await point). This means that another task will begin executing while remaining in the entered span. This results in an incorrect trace.

Instead of using `Span::enter` in asynchronous code, prefer the following:

- To enter a span for a synchronous section of code within an async block or function, prefer `Span::in_scope`. Since `in_scope` takes a synchronous closure and exits the span when the closure returns, the span will always be exited before the next await point. For example:

      async fn my_async_function() {
          let span = info_span!("my_async_function");

          let some_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 the `Future::instrument` combinator for attaching a span to a future (async function or block). This will enter the span every time the future is polled, and exit it whenever the future yields.

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

  ⓘ

      use tracing::Instrument;

      async fn my_async_function() {
          let span = 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 the callsite:

  ⓘ

      use tracing::Instrument;

      async fn my_async_function() {
          let some_value = some_other_async_function()
             .instrument(debug_span!("some_other_async_function"))
             .await;

          // ...
      }

- The `#[instrument]` attribute macro can automatically generate correct code when used on an async function:

  ⓘ

      #[tracing::instrument(level = "info")]
      async fn my_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

    #[macro_use] extern crate tracing;
    let span = span!(Level::INFO, "my_span");
    let guard = span.enter();

    // code here is within the span

    drop(guard);

    // code here is no longer within the span

Guards need not be explicitly dropped:

    #[macro_use] extern crate tracing;
    fn my_function() -> String {
        // enter a span for the duration of this function.
        let span = 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();
    }

    fn my_other_function() {
        // ...
    }

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

    #[macro_use] extern crate tracing;
    let span = 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!")

#### `pub fn in_scope<F: FnOnce() -> T, T>(&self, f: F) -> T` [src]

Executes the given function in the context of this span.

If this span is enabled, then this function enters the span, invokes `f` and then exits the span. If the span is disabled, `f` will still be invoked, but in the context of the currently-executing span (if there is one).

Returns the result of evaluating `f`.

# Examples

    let my_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:

    fn hello_world() -> String {
        "Hello world!".to_owned()
    }

    let span = info_span!("hello_world");
    // the span will be entered for the duration of the call to
    // `hello_world`.
    let a_string = span.in_scope(hello_world);

#### `pub fn field<Q: ?Sized>(&self, field: &Q) -> Option<Field> where
Q: AsField,` [src]

Returns a `Field` for the field with the given `name`, if one exists,

#### `pub fn has_field<Q: ?Sized>(&self, field: &Q) -> bool where
Q: AsField,` [src]

Returns true if this `Span` has a field for the given `Field` or field name.

#### `pub fn record<Q: ?Sized, V>(&self, field: &Q, value: &V) -> &Self where
Q: AsField,
V: Value,` [src]

Records that the field described by `field` has the value `value`.

This may be used with `field::Empty` to declare fields whose values are not known when the span is created, and record them later:

    use tracing::{trace_span, field};

    // Create a span with two fields: `greeting`, with the value "hello world", and
    // `parting`, without a value.
    let span = 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 a new value for a field whose value was already recorded:

    use tracing::info_span;

    // Initially, let's assume that our attempt to do something is going okay...
    let span = info_span!("doing_something", is_okay = true);
    let _e = span.enter();

    match do_something() {
        Ok(something) => {
            // ...
        }
        Err(_) => {
            // Things are no longer okay!
            span.record("is_okay", &false);
        }
    }

ⓘNote

    Note: The fields associated with a span are part of its
    Metadata.
    The Metadata. 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:

    use tracing::{trace_span, field};

    // Create a span with two fields: `greeting`, with the value "hello world", and
    // `parting`, without a value.
    let span = 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");

#### `pub fn record_all(&self, values: &ValueSet<'_>) -> &Self` [src]

Records all the fields in the provided `ValueSet`.

#### `pub fn is_disabled(&self) -> bool` [src]

Returns `true` if this span was disabled by the subscriber and does not exist.

See also `is_none`.

#### `pub fn is_none(&self) -> bool` [src]

Returns `true` if this span was constructed by `Span::none` and is empty.

If `is_none` returns `true` for a given span, then `is_disabled` will also return `true`. However, when a span is disabled by the subscriber rather than constructed by `Span::none`, this method will return `false`, while `is_disabled` will return `true`.

#### `pub fn follows_from(&self, from: impl Into<Option<Id>>) -> &Self` [src]

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

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

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

# Examples

Setting a `follows_from` relationship with a `Span`:

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

Setting a `follows_from` relationship with the current span:

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

Setting a `follows_from` relationship with a `Span` reference:

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

Setting a `follows_from` relationship with an `Id`:

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

#### `pub fn id(&self) -> Option<Id>` [src]

Returns this span's `Id`, if it is enabled.

#### `pub fn metadata(&self) -> Option<&'static Metadata<'static>>` [src]

Returns this span's `Metadata`, if it is enabled.

#### `pub fn with_subscriber<T>(
&self,
f: impl FnOnce((&Id, &Dispatch)) -> T
) -> Option<T>` [src]

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 returns `None` instead.

## Trait Implementations

### `impl Debug for EnteredSpan` [src]

#### `fn fmt(&self, f: &mut Formatter<'_>) -> Result` [src]

Formats the value using the given formatter. Read more

### `impl Deref for EnteredSpan` [src]

#### `type Target = Span`

The resulting type after dereferencing.

#### `fn deref(&self) -> &Span` [src]

Dereferences the value.

### `impl Drop for EnteredSpan` [src]

#### `fn drop(&mut self)` [src]

Executes the destructor for this type. Read more

## Auto Trait Implementations

### `impl !RefUnwindSafe for EnteredSpan` [src]

### `impl !Send for EnteredSpan` [src]

### `impl Sync for EnteredSpan` [src]

### `impl Unpin for EnteredSpan` [src]

### `impl !UnwindSafe for EnteredSpan` [src]

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `pub fn type_id(&self) -> TypeId` [src]

Gets the `TypeId` of `self`. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&self) -> &T` [src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut self) -> &mut T` [src]

Mutably borrows from an owned value. Read more

### `impl<T> From<T> for T` [src]

#### `pub fn from(t: T) -> T` [src]

Performs the conversion.

### `impl<T> Instrument for T` [src]

#### `fn instrument(self, span: Span) -> Instrumented<Self>ⓘ

### Notable traits for Instrumented<T>

`impl<T: Future> Future for Instrumented<T> type Output = T::Output;`
` [src]

Instruments this type with the provided `Span`, returning an `Instrumented` wrapper. Read more

#### `fn in_current_span(self) -> Instrumented<Self>ⓘ

### Notable traits for Instrumented<T>

`impl<T: Future> Future for Instrumented<T> type Output = T::Output;`
` [src]

Instruments this type with the current `Span`, returning an `Instrumented` wrapper. Read more

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(self) -> U` [src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>` [src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>` [src]

Performs the conversion.