26 lines
1.9 KiB
Markdown
26 lines
1.9 KiB
Markdown
# 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
|