1.9 KiB
gateway-heartbeat-telemetry Specification
Purpose
Define the bounded, low-cardinality gateway observations carried by authenticated heartbeats and their canonical units and exclusions.
Requirements
Requirement: Heartbeat carries observed gateway telemetry
Every authenticated GatewayHeartbeat SHALL carry the bounded process-level counters, delay totals and samples, control RTT/loss/jitter, pending reliable work, reconnect count, and provider state defined by GatewayTelemetry.
Scenario: Valid telemetry heartbeat
- WHEN a gateway reports its current observed snapshot
- THEN Go, Rust, and Swift bindings accept the same bounded low-cardinality values and units
Requirement: Heartbeat telemetry excludes sensitive dimensions
Heartbeat telemetry MUST reject unknown fields and MUST NOT include session, route, endpoint, credential, label, or payload values.
Scenario: Secret or high-cardinality field is attempted
- WHEN a heartbeat contains an unregistered session, route, endpoint, credential, or payload field
- THEN strict contract validation rejects it before authenticated transport
Requirement: Delay and egress observations have one canonical meaning
Queue delay SHALL measure provider-queue residence, processing delay SHALL measure active gateway recovery/framing/QUIC work excluding queue and pacing, and pacing delay SHALL measure scheduler waiting only. Processing samples SHALL count complete provider media units rather than Verse fragments. Measured egress SHALL derive from transmitted-byte deltas over monotonic elapsed time and MUST NOT be copied from configured capacity.
Scenario: One provider unit becomes multiple Verse frames
- WHEN one complete provider unit waits in the queue, traverses gateway processing, waits for pacing, and fragments into multiple Verse frames
- THEN each delay total includes only its defined interval and the heartbeat advances processing samples exactly once