Agent health metrics
The agent reports on its own health, so you can tell whether it is alive and whether its collector is running without logging in to the host. These liveness metrics are reported out-of-band, on a path that does not go through the collector. So they keep arriving even when the collector is down.
The metric catalog
Section titled “The metric catalog”The agent reports these metrics, all carrying the resource attributes below:
| Metric | Meaning |
|---|---|
kmagent.up | Heartbeat. Its absence is the signal that the agent, host, or network is down. |
kmagent.uptime | Time since the agent process started. |
kmagent.memory.rss | Agent process memory. |
kmagent.cpu.utilization | Agent process CPU. |
kmagent.collector.up | Whether the embedded collector is running (1 or 0), with state and reason attributes. |
Resource attributes: service.name is kmagent (so you can target it directly in dashboards and alerts), plus host.name, agent.version, collector.version, os.type, and host.arch.
What the collector status tells you
Section titled “What the collector status tells you”kmagent.collector.up carries a reason attribute that says why the collector is down, so you can tell the failure modes apart:
| Situation | Signal |
|---|---|
| Healthy | kmagent.collector.up=1, state=running |
| A bad configuration was pushed | kmagent.collector.up=0, reason=config_invalid |
| The collector exited with an error | kmagent.collector.up=0, reason=run_error |
| The collector panicked | kmagent.collector.up=0, reason=panic (then it auto-restarts) |
| A graceful shutdown | reason=shutdown |
The agent restarts the collector automatically after a crash.
Alerting on a silent agent
Section titled “Alerting on a silent agent”The one failure the agent cannot report is total silence. If the agent, host, or network goes down, nothing is emitted. Detect this with a dead-man’s-switch alert in KloudMate that fires when kmagent.up stops arriving for a host.
On by default, and tuning
Section titled “On by default, and tuning”Health reporting is on by default, so a freshly installed agent starts emitting these metrics without any extra step. To change how often it reports, or to turn it off, use the health-enabled and health-interval settings — either in the agent’s configuration file or as the KM_HEALTH_ENABLED and KM_HEALTH_INTERVAL environment variables. Set health-enabled: false (or KM_HEALTH_ENABLED=false) to stop reporting. The default interval is 60 seconds.
In autonomous auto-instrument mode the agent reports its health regardless of this setting.