Observability
Detent exposes what you need to answer two questions: is configuration fresh? and are reads succeeding?
Client Health
Section titled “Client Health”detent::HealthSnapshot h = client.health();{ "initialized": true, "source_connected": true, "accepted_version": 42, "staleness_seconds": 1.8, "knobs": 876, "cli_overrides": 1 }staleness_seconds is the monotonic time since the last successful update, or
since construction before the first. It’s the single most useful signal: a
distribution outage shows up here long before anyone notices a stale flag.
Client Metrics
Section titled “Client Metrics”client.metrics() returns process-wide atomic counters:
| Counter | Meaning |
|---|---|
reads_ok | Successful reads |
reads_missing | MissingKnob reads |
reads_conversion_failed | get_as conversion failures |
snapshot_swaps | Accepted updates published |
refresh_failures | Failed source polls or rejected updates |
stale_updates | Duplicate or older versions ignored |
source_connected | Current source state |
Labels are deliberately absent: no knob name, hash value, switch value, path or version ever becomes a metric dimension, so cardinality stays bounded and user identifiers never leak into monitoring.
Suggested Alerts
Section titled “Suggested Alerts”- Staleness.
staleness_secondsaboverefresh_alert_after(5 minutes by default). Tighten it for services whose kill switches must work within seconds. - Refresh failures.
refresh_failuresincreasing with nosnapshot_swapsfollowing. - Missing reads.
reads_missingabove zero, unless your process already aborts on them through_or_panic.
Daemon Health
Section titled “Daemon Health”GET /v1/healthon the authority.detent-authority --statusanddetent-agent --statusfrom the command line.- Daemon logs, described in Logging.
What’s Never Logged
Section titled “What’s Never Logged”Hash values, switch values and knob values are never logged, and rejected publishes are logged by category without their payload. Hash and switch values are often user or tenant identifiers.