Collector health states explained
Healthy, Degraded, Offline, Enrollment Pending, Update Required and Revoked — what each state means and what to check.
Overview
Each collector reports a heartbeat every 60 seconds. The control plane derives a single health state from the heartbeat history, reported metrics, credential status and version, so operators can triage at a glance instead of reading raw telemetry.
State reference
| State | Meaning | Typical cause |
|---|---|---|
| Healthy | Recent heartbeat, current version, no reported resource pressure | Normal operation |
| Degraded | Heartbeating, but under resource pressure or with clock skew beyond tolerance | High CPU/memory on host, or NTP drift |
| Offline | No heartbeat received for more than 5 minutes | Host down, service stopped, or network/egress path broken |
| Enrollment Pending | Installed but has not completed its first successful enrollment exchange | Invalid, expired or revoked token, or blocked connectivity |
| Update Required | Running a version far enough behind the current release channel | Auto-upgrade disabled, blocked, or repeatedly rolled back |
| Revoked | Credential invalidated by an operator | Deliberate retirement or security response |
Degraded in detail
Degraded means the collector is still reachable and heartbeating, but something about its own health reduces confidence in the timeliness or completeness of what it reports — commonly sustained high resource utilization on the host, or a clock more than 5 seconds out of sync with the control plane, which affects mTLS and heartbeat timing precision.
- AIQ-COL-003Collector degradedThe collector is heartbeating but under resource pressure or has clock skew beyond the 5-second tolerance, reducing confidence in its reported evidence.
Offline in detail
A single missed heartbeat does not trigger Offline. The state only changes after more than 5 minutes with no heartbeat, which is long enough to rule out a brief network blip while still catching a real outage quickly.
Credential-related states
Enrollment Pending and Revoked are both credential states rather than connectivity states: a collector stuck in Enrollment Pending has never successfully authenticated, and one marked Revoked has had a previously valid credential deliberately invalidated. Neither will resume normal reporting without operator action — re-enrolling with a fresh token in the pending case, or a brand-new enrollment in the revoked case.
- AIQ-COL-004Collector credential expiring or expiredThe collector's permanent credential is approaching or past its validity window.
- AIQ-COL-005Collector revokedThe collector's credential has been deliberately invalidated and it can no longer authenticate to the control plane.
Escalation path
Use this article to identify what a state means, then follow the linked symptom-first guide for the specific fix.
- Troubleshoot Offline CollectorSymptom-first guide for AIQ-COL-001 with exact checks in order.
- Enrollment failuresSymptom-first guide for AIQ-ENR-001 through AIQ-ENR-004: token, expiry, revocation and connectivity failures during enrollment.
- Update failuresSymptom-first guide for AIQ-UPD-001 through AIQ-UPD-003: verification failures, maintenance-window blocks and rollbacks.
- Uninstall and revoke a collectorHow to retire a collector cleanly: uninstall the host software and revoke its credential so it cannot re-authenticate.