Module metrics 

What the write actor knows about its own latency (T1.4, D-079).

Why this exists

crate::CHUNK_BUDGET is 3 ms and the crate has, until now, had exactly one way to find out whether that bound holds: run benches/budgets.rs on a synthetic fixture. That is a statement about a laptop, not about a database in use. D-059 already established that the bound does not hold on a large file, by a factor of 15, and it took a benchmark rewrite to notice — because nothing in the running system was counting.

Tier 1’s other three items are all “make the tail bounded”. None of them can be validated in the field without something that measures the tail, which is why this is a precondition for them rather than a nice-to-have.

What is recorded, and what is deliberately not

Four things, all of them per actor turn — one command, start to finish:

• queue depth on both channels, sampled before the turn begins;
• hold duration, bucketed, per command kind;
• holds over budget, counted separately per kind;
• the longest hold since open, with the kind that caused it.

The hold is the whole turn, not the execute call’s SQL. That is the quantity the budget is about: the SQLite write lock is not preemptible, so an interactive assertion arriving mid-turn waits for the turn, whatever the turn spent its time on.

There is no per-command timestamp trail and no sampling of individual slow commands. That would be a tracing problem, and tracing is already a dependency — spans belong there. This module answers one question (“is the bound holding, and if not, which kind breaks it”) in fixed memory, with no allocation on the actor’s path.

The feature gate

Behind metrics, off by default. With the feature off, ActorMetrics is a zero-sized type whose methods compile away and HoldTimer::start does not read the clock — so the actor loop has one shape either way. That matters more than the nanoseconds: a #[cfg] in the loop body is how the instrumented and uninstrumented paths drift until only one of them is the one that runs.

Structs

ActorMetrics

The metrics-off shape: zero-sized, and every method is nothing.

HoldTimer

Times one actor turn.

Enums

CommandKind

The command kinds the actor can spend a turn on.

Constants

BUCKET_BOUNDS_MICROS

Upper bounds of the hold-duration histogram, in microseconds.

BUCKET_COUNT

Number of histogram buckets, including the overflow bucket.