Module timing 

Per-stage wall-clock timing instrumentation.

Gated on the MCPR_STAGE_TIMING env var, checked once per process and cached via OnceLock. When disabled, StageTimer::mark is a no-op and StageTimer::finish returns None — ~1 ns of overhead from a cached branch predict.

When enabled, timings populate crate::event::StageTimings which handlers attach to each RequestEvent. Events flow through the existing event bus, so sinks (stderr JSON, sqlite, cloud) pick them up without extra wiring.

Enabling

MCPR_STAGE_TIMING=1 mcpr proxy run ./mcpr.toml
# or
MCPR_STAGE_TIMING=true mcpr proxy run ...

Reading the data

The JSON stderr sink (default log format) writes each event — including stage_timings — as one JSON line to the proxy’s log file at ~/.mcpr/proxies/<name>/proxy.log. To aggregate:

tail -n +N ~/.mcpr/proxies/bench/proxy.log \
    | jq -c 'select(.stage_timings)' \
    | jq -s '[.[].stage_timings.schema_us // empty] | sort'

The benches/scripts/scenarios/where-time-goes.sh harness does this aggregation automatically and prints a per-stage summary.

Structs

StageTimer

Lightweight per-request stopwatch. Creation and every mark() are no-ops when MCPR_STAGE_TIMING is not set — safe to sprinkle liberally through hot paths.

Enums

Stage

Named stages the pipeline reports timings for. Keep this list aligned with the Option<u32> fields on crate::event::StageTimings.