Struct SpanCache 

pub struct SpanCache<P: EnabledPredicate = LevelPredicate> { /* private fields */ }

A tracing::Subscriber that holds spans in memory for inspection.

Open spans live in a sharded Box<[Mutex<Slab<SpanRecord>>]>, with the lane count set by CacheConfig::lane_count (default crate::DEFAULT_LANE_COUNT). The shard is picked by a thread-local key; the slab gives an O(1) cache-friendly index, and the user-facing tracing::span::Id packs (shard, slab_idx+2) into a single u64 so SPAN_STACK push/pop and trait-method dispatch don’t need a separate lookup. When a span closes it moves to a per-thread buffer and is flushed to the Driver via a spillway channel.

SpanRecord.id is an actual_id (separate from the tracing id) that serves as the BTreeMap key, since slab indices are reused. IDs are monotonic within a thread’s ID_BATCH-sized reservation; across threads they interleave, so map order reflects allocation order per-thread but not strict global creation order.

Create with SpanCache::new / SpanCache::with_predicate (defaults) or SpanCache::with_config / SpanCache::with_predicate_and_config (custom batch sizes & lane count). Each returns (SpanCache, Driver); spawn the Driver as a background task to commit closed spans.

Implementations

impl SpanCache<LevelPredicate>

pub fn new(capacity: usize) -> (Self, Driver)

Default predicate (TRACE), default config.

pub fn with_config(capacity: usize, config: CacheConfig) -> (Self, Driver)

Default predicate (TRACE) with a custom CacheConfig.

impl<P: EnabledPredicate> SpanCache<P>

pub fn with_predicate(capacity: usize, predicate: P) -> (Self, Driver)

Custom predicate, default CacheConfig.

pub fn with_predicate_and_config( capacity: usize, predicate: P, config: CacheConfig, ) -> (Self, Driver)

Custom predicate and custom CacheConfig.

pub fn lane_count(&self) -> usize

Number of in-flight slab shards this cache uses.

pub fn get_span(&self, actual_id: u64) -> Option<SpanRecord>

Returns a closed span by its actual_id (SpanRecord.id). This is the id stored in parent_id and used as the BTreeMap key. Only closed spans are reachable here.

pub fn clear(&self)

Drop every closed span currently in the BTreeMap. Called by the host when the cache-recording level transitions to OFF so a paused host doesn’t keep stale data around to confuse the next session. In-flight spans (still open in the slabs) are not affected; if any close after this call they’ll repopulate the map as normal.

pub fn actual_id_for(&self, tracing_id: u64) -> Option<u64>

Resolve the actual_id (i.e. the SpanRecord::id used as the BTreeMap key after close) for an in-flight span addressed by its tracing::span::Id u64. Lock-free Acquire load from the per-shard sidecar — does not touch the slab Mutex.

pub fn page(&self, after_id: u64, limit: usize) -> Vec<SpanRecord>

Returns closed spans in ascending actual_id order. Open spans are not included; call Self::flush_pending + Driver::drain_sync first if you need just-closed spans to appear.

pub fn flush_pending(&self)

Drains the calling thread’s two PENDING buffers (spans + events) into their respective spillway channels. Must be called before Driver::drain_sync in tests to ensure all recently-closed spans and emitted events are delivered.

Trait Implementations

impl<P: EnabledPredicate> Subscriber for SpanCache<P>

fn max_level_hint(&self) -> Option<LevelFilter>

Returns the highest verbosity level that this Subscriber will enable, or None, if the subscriber does not implement level-based filtering or chooses not to implement this method.

fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest

Registers a new callsite with this subscriber, returning whether or not the subscriber is interested in being notified about the callsite.

fn enabled(&self, metadata: &Metadata<'_>) -> bool

Returns true if a span or event with the specified metadata would be recorded.

fn event_enabled(&self, event: &Event<'_>) -> bool

Determine if an Event should be recorded.

fn new_span(&self, attrs: &Attributes<'_>) -> Id

Visit the construction of a new span, returning a new span ID for the span being constructed.

fn record(&self, span: &Id, values: &Record<'_>)

Record a set of values on a span.

fn record_follows_from(&self, _span: &Id, _follows: &Id)

Adds an indication that span follows from the span with the id follows.

fn event(&self, event: &Event<'_>)

Records that an Event has occurred.

fn enter(&self, span: &Id)

Records that a span has been entered.

fn exit(&self, _span: &Id)

Records that a span has been exited.

fn try_close(&self, id: Id) -> bool

Notifies the subscriber that a span ID has been dropped, and returns true if there are now 0 IDs that refer to that span.

fn on_register_dispatch(&self, subscriber: &Dispatch)

Invoked when this subscriber becomes a Dispatch.

fn clone_span(&self, id: &Id) -> Id

Notifies the subscriber that a span ID has been cloned.

fn drop_span(&self, _id: Id)

👎Deprecated since 0.1.2:

use Subscriber::try_close instead

This method is deprecated.

fn current_span(&self) -> Current

Returns a type representing this subscriber’s view of the current span.

unsafe fn downcast_raw(&self, id: TypeId) -> Option<*const ()>

If self is the same type as the provided TypeId, returns an untyped *const pointer to that type. Otherwise, returns None.