Docket telemetry

Docket emits operational spans and durable domain facts below [:docket, ...]. Span and pruner durations use native monotonic units; reporters convert them. Counts and gauges are measurements. Use Docket.Telemetry.metric_metadata/2 for core metric labels and Docket.Postgres.Telemetry.metric_metadata/2 for PostgreSQL labels. Raw domain events may contain identities for logs and traces, but those values must never become labels. Claim tokens are never emitted.

Operational catalog

| [:docket, :postgres, :vehicle, :stop|:exception] | duration | result | | [:docket, :postgres, :vehicle, :discard] | count | stage, result | | [:docket, :postgres, :vehicle, :crash] | count, claim_held_ms, claim_attempt | result | | [:docket, :postgres, :vehicle, :drain] | committed_moments, elapsed_ms, claim_held_ms, claim_attempt | outcome, budget | | [:docket, :postgres, :pruner, :pass] | deleted-row counts and duration | result |

Lifecycle and nested store spans share a raw lifecycle_ref; the metric projection drops it. Committed facts and observer work start only after the outer transaction succeeds. Stale fences and rollbacks therefore emit no committed fact. Observer completion means only that the callback returned after durable success, not that an external system durably accepted an effect. Claim selection/attempt and store events are operational attempt facts and may describe work later rolled back; only [:docket, :lifecycle, :committed] and the domain events are durable-success facts.

Use Ecto repository telemetry for checkout, queue, and query duration. Active vehicles are execution processes, not checked-out connections: slow node work can raise in_flight without holding a database connection.

Claims fence durable state only. A stolen claim can execute node code and external effects more than once even though only one moment commits. External effects require their own stable idempotency scheme.

Admission evidence boundary

Every claim policy keeps the generic ClaimPolicy and claim events in the catalog above. The admission event reports total duration and a normalized contentions count; the contention_phase label is retained for shape stability and is always :none for the shipped engines. Tenant ID, raw scope_key, run or graph identity, and claim token are forbidden as ordinary metric labels.

Admission release counts use the bounded reasons future, external, terminal, and signal; they never carry tenant or run identity.

Repository timing and query-plan benchmarks are regression evidence for admission behavior, including the cross-scope fairness and cohort-stickiness scenarios that exercise the windowed engine.

Benchmark derivations

• Throughput: rate of lifecycle.committed.count; checkpoint and superstep advancement come from its checkpoint_seq and step measurements.
• End-to-end and database latency percentiles: histogram the native duration measurements on lifecycle, store, poll, launch, graph, codec, and node events.
• Active work and demand: last-value gauges from dispatcher state.in_flight and state.demand. Compare with Ecto checkout telemetry; active node work must not imply a checked-out connection.
• Claim health: rates and histograms for claim leases, steals, poisoned, claim_attempts, operation results, matched, fence-loss stage, and vehicle claim_held_ms.
• Cache behavior: cache hit ratio is hit / (hit + miss + incompatible + generation_invalidated) from graph-cache fetch results.
• Logical write amplification: sum store attempted_rows and encoded_bytes per committed lifecycle count, correlated by the raw lifecycle_ref; these describe requested work and may include rolled-back or idempotent attempts. Use Ecto query telemetry and database statistics when physical affected-row or WAL amplification is required. Reads use selected_rows and are excluded.
• Retry and park behavior: group committed lifecycle counts by disposition; :retry, :timer, and :budget are durable outcomes, not proposed work.
• Prune impact: compare deleted-row and cascade rates and pass latency with lifecycle throughput and store bytes before and after each pass.

The vehicle drain's elapsed_ms and claim_held_ms are explicit millisecond business measurements. Fields named duration use native telemetry monotonic units.