Arc<Mutex>

Guides

Rust walkthroughs

ā† Back to all guides

What is the difference between tracing::Span::enter and Span::in_scope for span activation?

tracing::Span::enter returns an Entered guard that keeps the span active for the duration of the guard's lifetime, while Span::in_scope takes a closure and activates the span only for the closure's execution, returning the closure's result. The key difference is how they manage the span's lifetime: enter requires managing an RAII guard that must stay in scope, whereas in_scope provides a more structured approach that ensures the span is exited immediately after the closure completes. Both methods make the span the current span in the thread-local context, but in_scope prevents common mistakes like storing the Entered guard in a field or returning it from a function, which would break the parent-child span relationship.

What is a Span in tracing?

use tracing::{info, span, Level};
 
// A span represents a period of time during which something happens
// Spans form a tree structure - the current span is the "active" one
// Events are logged in the context of the current span
 
#[tracing::instrument]
fn process_order(order_id: u32) {
    // This creates a span named "process_order"
    // Events inside are associated with this span
    info!("Processing order {}", order_id);
    
    let validate_span = span!(Level::INFO, "validate");
    // Child span - will be nested under process_order
}

Spans provide context for events and can be nested to form a hierarchy.

Basic Span Activation

use tracing::{span, Level, info};
 
fn main() {
    let span = span!(Level::INFO, "my_span", request_id = 123);
    
    // Without activation, the span doesn't appear in traces
    info!("Not inside any span");
    
    // With activation, events are recorded under the span
    let _enter = span.enter();
    info!("Inside my_span");
    // _enter goes out of scope here, exiting the span
}

Span activation makes a span the "current" span for the thread, affecting all events emitted during that scope.

Span::enter Returns an RAII Guard

use tracing::{span, Level, info};
 
fn demonstrate_enter() {
    let my_span = span!(Level::INFO, "my_span");
    
    // enter() returns an Entered guard
    // The span is active while the guard exists
    let guard = my_span.enter();
    
    info!("This event is inside my_span");
    
    // Guard can be explicitly dropped
    drop(guard);
    
    info!("This event is NOT inside my_span");
    
    // Pattern with underscore to suppress unused warning
    let _guard = my_span.enter();
    info!("Also inside my_span");
    // _guard dropped at end of scope
}

enter returns an Entered<'_, Span> guard that keeps the span active until dropped.

Span::in_scope Takes a Closure

use tracing::{span, Level, info};
 
fn demonstrate_in_scope() {
    let my_span = span!(Level::INFO, "my_span");
    
    // in_scope takes a closure and returns its result
    let result = my_span.in_scope(|| {
        info!("This event is inside my_span");
        42 // Return value
    });
    
    info!("This event is NOT inside my_span");
    
    assert_eq!(result, 42);
}

in_scope activates the span only for the closure's execution, automatically exiting afterward.

Lifetime Management Comparison

use tracing::{span, Level, info};
 
fn enter_lifetime() {
    let my_span = span!(Level::INFO, "my_span");
    
    // With enter(), the span stays active until the guard is dropped
    {
        let _guard = my_span.enter();
        info!("Inside scope");
    } // Guard dropped here
    
    info!("Outside scope");
}
 
fn in_scope_lifetime() {
    let my_span = span!(Level::INFO, "my_span");
    
    // With in_scope(), the span is only active for the closure
    my_span.in_scope(|| {
        info!("Inside closure");
    }); // Span exits immediately here
    
    info!("Outside closure");
}

Both achieve the same result, but in_scope makes the lifetime boundary explicit.

The Dangers of Storing Entered Guards

use tracing::{span, Level, info};
 
struct BadService {
    // DON'T DO THIS: Storing Entered guards in structs
    // This breaks the span hierarchy and thread-local state
    // span_guard: tracing::span::Entered<'static, tracing::Span>,
}
 
// Problem 1: Guard returned from function
fn leak_guard() -> tracing::span::Entered<'static, tracing::Span> {
    let span = span!(Level::INFO, "leaked");
    // ERROR: Cannot return guard - lifetime doesn't match
    // span.enter()
    todo!()
}
 
// Problem 2: Guard stored in collection
fn store_guards() {
    let span = span!(Level::INFO, "stored");
    let mut guards = Vec::new();
    
    // This would work but is problematic
    // guards.push(span.enter());
    // guard persists longer than expected
    
    // in_scope prevents this pattern entirely
    span.in_scope(|| {
        // Cannot accidentally store the guard
        // It only exists for the closure
    });
}

in_scope prevents common mistakes by not exposing the guard at all.

Nested Spans

use tracing::{span, Level, info};
 
fn nested_spans() {
    let parent = span!(Level::INFO, "parent");
    let child = span!(Level::INFO, "child");
    
    // With enter():
    let _parent_guard = parent.enter();
    info!("In parent span");
    
    {
        let _child_guard = child.enter();
        info!("In child span, parent is still in context");
    }
    
    info!("Back in parent span");
    
    // With in_scope:
    parent.in_scope(|| {
        info!("In parent span");
        
        child.in_scope(|| {
            info!("In child span, nested under parent");
        });
        
        info!("Back in parent span");
    });
}

Both approaches support nested spans, but in_scope makes the nesting structure more visible.

Async Code and Span Activation

use tracing::{span, Level, info};
 
// CRITICAL: Span guards should NOT be held across await points
async fn bad_async_span() {
    let span = span!(Level::INFO, "async_operation");
    let _guard = span.enter(); // BAD: guard held across await
    
    info!("Before await");
    
    // PROBLEM: The guard is still active, but the task may resume
    // on a different thread where the span context is wrong
    some_async_work().await;
    
    info!("After await"); // Span context may be incorrect
}
 
async fn good_async_span() {
    let span = span!(Level::INFO, "async_operation");
    
    // Option 1: Use in_scope for synchronous sections
    span.in_scope(|| {
        info!("Synchronous work inside span");
    });
    
    some_async_work().await;
    
    span.in_scope(|| {
        info!("More synchronous work");
    });
}
 
async fn some_async_work() {
    // Simulated async work
}

For async code, use in_scope for synchronous sections and avoid holding guards across await points.

Using instrument() for Async Code

use tracing::{instrument, info};
 
// The instrument attribute handles async span activation correctly
#[instrument(skip_all)]
async fn process_request(user_id: u32) {
    info!("Processing request");
    fetch_user(user_id).await;
    info!("User fetched");
}
 
async fn fetch_user(user_id: u32) {
    info!("Fetching user {}", user_id);
}
 
// Manual equivalent with in_scope:
async fn process_request_manual(user_id: u32) {
    let span = tracing::span!(tracing::Level::INFO, "process_request");
    
    span.in_scope(|| info!("Processing request"));
    
    // For async sections, instrument the future
    fetch_user(user_id).instrument(span.clone()).await;
    
    span.in_scope(|| info!("User fetched"));
}

The #[instrument] attribute and instrument() combinator handle async span activation correctly.

Cloning Spans for Multiple Uses

use tracing::{span, Level, info};
 
fn cloned_spans() {
    let original = span!(Level::INFO, "original");
    
    // Spans are cheap to clone (reference-counted)
    let cloned = original.clone();
    
    original.in_scope(|| {
        info!("In original span");
    });
    
    cloned.in_scope(|| {
        info!("In cloned span - same span context");
    });
    
    // Both refer to the same span
    // Entering either activates the same span
}

Spans are reference-counted, making cloning cheap for use across multiple scopes.

Return Values with in_scope

use tracing::{span, Level, info};
 
fn compute_value() -> i32 {
    let span = span!(Level::INFO, "compute");
    
    // in_scope returns the closure's return value
    let result = span.in_scope(|| {
        info!("Computing...");
        let x = 10 + 5;
        x * 2
    });
    
    result
}
 
// Pattern: Wrap function calls
fn wrap_call<T, F>(span: tracing::Span, f: F) -> T
where
    F: FnOnce() -> T,
{
    span.in_scope(f)
}

in_scope propagates return values, making it easy to wrap computations.

Error Handling with in_scope

use tracing::{span, Level, info};
 
fn fallible_operation() -> Result<String, &'static str> {
    let span = span!(Level::INFO, "fallible");
    
    // in_scope propagates Result
    span.in_scope(|| {
        info!("Attempting operation");
        if rand::random() {
            Ok("success".to_string())
        } else {
            Err("operation failed")
        }
    })
}
 
// With enter(), the pattern is more verbose
fn fallible_with_enter() -> Result<String, &'static str> {
    let span = span!(Level::INFO, "fallible");
    let _guard = span.enter();
    
    info!("Attempting operation");
    if rand::random() {
        Ok("success".to_string())
    } else {
        Err("operation failed")
    }
}

in_scope works naturally with functions that return Result or other values.

Comparison Table

Feature enter in_scope
Returns Entered<'_, Span> Closure's return value
Scope management RAII guard Closure body
Can be stored Yes (dangerous) No
Can be returned No (lifetime issues) N/A (closure-based)
Structured code Guard in scope Closure-based
Return value None Propagated
Error handling Manual Natural
Async safety Dangerous across await Safe for sync sections
Explicit lifetime Guard lifetime Closure body

When to Use Each

use tracing::{span, Level, info};
 
fn when_to_use() {
    let span = span!(Level::INFO, "example");
    
    // Use enter when:
    // 1. You need a variable number of events in the span
    // 2. The span should cover multiple statements
    // 3. Guard can't escape the function
    
    {
        let _guard = span.enter();
        info!("Event 1");
        // ... more code ...
        info!("Event 2");
    }
    
    // Use in_scope when:
    // 1. Clear start/end boundaries are desired
    // 2. You want to return a value
    // 3. You want to prevent guard misuse
    // 4. The span covers a single logical operation
    
    let value = span.in_scope(|| {
        info!("Single operation");
        compute_value()
    });
}
 
fn compute_value() -> i32 { 42 }

Choose enter for flexible scope control; choose in_scope for structured, safe span activation.

Thread Safety and Span Context

use tracing::{span, Level, info};
use std::thread;
 
fn thread_safety() {
    let span = span!(Level::INFO, "thread_span");
    
    // Each thread has its own span context
    // enter/in_scope affect only the current thread
    
    let handle1 = thread::spawn(|| {
        let local_span = span!(Level::INFO, "thread1");
        local_span.in_scope(|| {
            info!("In thread 1's span");
        });
    });
    
    let handle2 = thread::spawn(|| {
        let local_span = span!(Level::INFO, "thread2");
        local_span.in_scope(|| {
            info!("In thread 2's span");
        });
    });
    
    // span.enter() here doesn't affect other threads
    let _guard = span.enter();
    info!("In main thread's span");
    
    handle1.join().unwrap();
    handle2.join().unwrap();
}

Span context is thread-local; enter and in_scope only affect the current thread.

Real-World Example: HTTP Handler

use tracing::{span, Level, info, instrument};
 
// Using instrument attribute (recommended for functions)
#[instrument(skip(request))]
async fn handle_request(request: Request) -> Response {
    info!("Handling request");
    
    // Nested spans for sub-operations
    let db_span = span!(Level::INFO, "database_query");
    let user = db_span.in_scope(|| {
        info!("Querying database");
        query_user(request.user_id)
    });
    
    let cache_span = span!(Level::INFO, "cache_lookup");
    let cached = cache_span.in_scope(|| {
        info!("Checking cache");
        check_cache(request.key)
    });
    
    Response { user, cached }
}
 
fn query_user(id: u32) -> User { User { id } }
fn check_cache(key: &str) -> bool { true }
 
struct Request { user_id: u32, key: String }
struct Response { user: User, cached: bool }
struct User { id: u32 }

Use in_scope for clearly bounded sub-operations within a function.

Real-World Example: Transaction Span

use tracing::{span, Level, info};
 
fn process_transaction(tx_id: u64) -> Result<(), Error> {
    let tx_span = span!(Level::INFO, "transaction", id = tx_id);
    
    // in_scope naturally wraps the transaction phases
    let validate_result = tx_span.in_scope(|| {
        info!("Validating transaction");
        validate()
    })?;
    
    let execute_result = tx_span.in_scope(|| {
        info!("Executing transaction");
        execute(validate_result)
    })?;
    
    tx_span.in_scope(|| {
        info!("Committing transaction");
        commit(execute_result)
    })
}
 
fn validate() -> Result<ValidateResult, Error> { Ok(ValidateResult) }
fn execute(_: ValidateResult) -> Result<ExecuteResult, Error> { Ok(ExecuteResult) }
fn commit(_: ExecuteResult) -> Result<(), Error> { Ok(()) }
 
struct ValidateResult;
struct ExecuteResult;
struct Error;

in_scope works well for sequential operations with clear boundaries and error propagation.

Real-World Example: Debugging Scope Issues

use tracing::{span, Level, info};
 
fn debugging_example() {
    let outer = span!(Level::INFO, "outer");
    let inner = span!(Level::INFO, "inner");
    
    // Common bug: accidentally exiting span early
    outer.in_scope(|| {
        info!("In outer");
        
        // This is correct
        inner.in_scope(|| {
            info!("In inner (nested under outer)");
        });
        
        info!("Back in outer");
        
        // This is also correct with in_scope - can't accidentally extend
    });
    
    // With enter, this bug is possible:
    let _outer = outer.enter();
    info!("In outer");
    
    // Bug: forgetting to drop inner guard
    let _inner = inner.enter();
    info!("In inner");
    // If _inner were assigned to a longer-lived variable...
    // it would incorrectly stay active
    
    info!("Still in outer");
}

in_scope prevents accidental scope extension by enforcing the boundary.

Synthesis

Key differences:

Aspect enter in_scope
API style Guard-based Closure-based
Scope boundary Guard drop Closure end
Misuse potential Storable guard Not storable
Return propagation None Automatic
Best for Variable scope length Fixed operation

Common patterns:

Pattern Recommended
Single operation in_scope
Multiple statements enter (with caution)
Returning values in_scope
Async code instrument or in_scope per sync section
Nested spans Either, but in_scope is clearer
Error handling in_scope

Best practices:

  1. Prefer in_scope for structured, bounded operations
  2. Use #[instrument] for async functions
  3. Never store Entered guards in structs or return them
  4. Never hold guards across await points
  5. Use enter only when scope length needs to vary
  6. Clone spans cheaply for multiple uses

Key insight: enter and in_scope both activate a span in the current thread's context, but differ in how they manage scope. enter returns an RAII guard that exits the span when droppedā€”this provides flexibility but enables misuse when guards are stored or held too long. in_scope takes a closure and activates the span only for the closure's execution, preventing guard misuse by design. The closure-based approach naturally propagates return values and makes scope boundaries explicit. For async code, neither approach should hold activation across await points; use the #[instrument] attribute or .instrument(span) on futures instead. The choice between them is a trade-off between flexibility (enter) and safety (in_scope), with in_scope being the safer default for most cases.