Struct ExplainStore 

pub struct ExplainStore { /* private fields */ }

A bounded, in-memory store of recent request explanations.

A single-instance affordance backing /debug/explain/{request_id} (docs/05 §5 ring buffer). Oldest entries are evicted past capacity, so memory is bounded regardless of traffic.

It retains the assembled trace, not a serialized document: /debug/explain is read for a vanishing fraction of requests, so building the JSON eagerly on every request was pure waste (~12µs/req of allocation + serialization). The doc is built lazily in ExplainStore::get instead; record only clones the (small, owned) trace and pushes it under the lock.

A single lock (not sharded): record’s per-request contention was measured to be dominated by the trace clone, not the lock — even one uncontended mutex under 16 threads matched a 16-way sharded one, because the allocation is the cost. Cloning the trace before taking the lock (below) keeps the critical section to an O(1) deque op, and a fast concurrent allocator (the binary’s mimalloc) is what actually relieves the clone’s cost.

Implementations

impl ExplainStore

pub fn new(capacity: usize) -> Self

Creates a store holding at most capacity recent explanations.

pub fn record(&self, request_id: RequestId, trace: &RequestTrace)

Records the trace for request_id, evicting the oldest if full. Retains the trace as-is, the explain document is assembled lazily on Self::get.

pub fn get(&self, request_id: &RequestId) -> Option<Value>

Looks up request_id and assembles its explanation document, if retained. The JSON is built here (read time), not at record time.

Trait Implementations

impl Debug for ExplainStore

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.