Struct SpanCache 

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

A tracing::Subscriber that funnels closed spans to live consumers.

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.

The cache itself holds no closed spans — the driver fans each one out to SpanCache::subscribe receivers and then drops it. Late events (an event whose parent span has already been fanned out) have nowhere to land and are dropped.

SpanRecord.id is an actual_id (separate from the tracing id), monotonic within a thread’s ID_BATCH-sized reservation; across threads they interleave, so subscriber-observed order is driver-commit (close-time) order, not strict global open 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 fan closed spans out to subscribers.

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 actual_id_for(&self, tracing_id: u64) -> Option<u64>

Resolve the actual_id (i.e. the SpanRecord::id published on the fan-out stream) 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 subscribe(&self, capacity: u64) -> Receiver<SpanRecord>

Register a new subscriber. The returned Receiver yields every closed span the cache produces from this call onward, in the driver’s commit (close-time) order. The cache holds no history — if you need to see spans from before the call, subscribe earlier.

Replaces the previous page(after_id, _) API, which keyed on open-order actual_id and so silently dropped spans whenever close order diverged from open order — the norm under async workloads.

capacity is the soft cap on in-flight spans for this subscriber. When the receiver falls behind by that much, the driver logs and drops a whole batch — slow consumers don’t back up the pipeline. Drop the receiver to unsubscribe; the driver prunes the sender lazily on the next fan-out.

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.