Polling cadence
The interface is pull only. QuantumTouch does not push, stream, or open a
webhook toward a monitoring system. (Outbound audit shipping, described later, is
a separate and explicitly configured mechanism, and it ships audit records — not
telemetry.)
Endpoints carry short server-side caches so that several UI tabs and a polling
NMS share one upstream request rather than multiplying load on the controller and
the data plane. The cache is process-local and reset on restart. Only successful
responses are cached, so a transient upstream error is never replayed for a full
cache lifetime.
| Endpoint | Server cache | Suggested client interval |
|---|---|---|
/health |
1 s | 5–15 s |
/counters |
1 s | 2–10 s |
/counters/{ip} |
none | on demand |
/access |
30 s | 60 s |
/about |
30 s | 300 s or on change |
/drivers |
60 s | 300 s or on demand |
/hardware |
10 s (shared IPMI cache) | 30–60 s |
/dataplane-stats |
stateful — see below | 5 s, single collector |
/throughput/recent, /metrics/query_range |
none needed | 5–30 s |
/events |
30 s (uplink probe), 10 s (IPMI) | 5–15 s |
/audit/timeline |
none | 10–60 s, with cursor |
Two endpoints deserve specific care.
GET /api/bng/dataplane-stats is stateful, not a gauge read. It reports the
delta since the previous request to that endpoint, divided by elapsed wall
time. Three consequences follow. The first call after a process restart returns
zero rates, because there is no prior sample. Calls less than half a second apart
return zero rates, by a divide-by-tiny guard. And two independent clients
polling concurrently steal each other's window — each sees only the traffic
since the other's call. Designate a single collector for this endpoint, or use
the Prometheus interface counters instead.
GET /api/bng/events has write side effects. Synthesising the live event set
reconciles it against the persisted history, which updates the history file and
appends lifecycle transitions to the audit log. It is not a safe or idempotent
GET in the HTTP sense. This is by design — the event lifecycle advances on
observation — but it means the endpoint should be polled by one collector at a
sane interval, not fanned out.