Set agent statuses

Agent statuses reflect the health of a Telegraf instance based on runtime data. The Telegraf heartbeat output plugin evaluates Common Expression Language (CEL) expressions against agent metrics, error counts, and plugin statistics to determine the status sent with each heartbeat.

Status values

Telegraf Controller displays the following agent statuses:

How status evaluation works

You define CEL expressions for ok, warn, and fail in the [outputs.heartbeat.status] section of your heartbeat plugin configuration. Telegraf evaluates expressions in a configurable order and assigns the status of the first expression that evaluates to true.

For full details on evaluation flow, configuration options, and available variables and functions, see the Agent status evaluation reference.

Configure agent statuses

To configure status evaluation, add "status" to the include list in your heartbeat plugin configuration and define CEL expressions in the [outputs.heartbeat.status] section.

Example: Basic health check

Report ok when metrics are flowing. If no metrics arrive, fall back to the fail status.

[[outputs.heartbeat]]
  url = "http://telegraf_controller.example.com/agents/heartbeat"
  instance_id = "&{agent_id}"
  token = "${TELEGRAF_CONTROLLER_TOKEN}"
  interval = "1m"
  include = ["hostname", "statistics", "configs", "logs", "status"]

  [outputs.heartbeat.status]
    ok = "metrics > 0"
    default = "fail"

Example: Error-based status

Warn when errors are logged, fail when the error count is high.

[[outputs.heartbeat]]
  url = "http://telegraf_controller.example.com/agents/heartbeat"
  instance_id = "&{agent_id}"
  token = "${TELEGRAF_CONTROLLER_TOKEN}"
  interval = "1m"
  include = ["hostname", "statistics", "configs", "logs", "status"]

  [outputs.heartbeat.status]
    ok = "log_errors == 0 && log_warnings == 0"
    warn = "log_errors > 0"
    fail = "log_errors > 10"
    order = ["fail", "warn", "ok"]
    default = "ok"

Example: Composite condition

Combine error count and buffer pressure signals.

[[outputs.heartbeat]]
  url = "http://telegraf_controller.example.com/agents/heartbeat"
  instance_id = "&{agent_id}"
  token = "${TELEGRAF_CONTROLLER_TOKEN}"
  interval = "1m"
  include = ["hostname", "statistics", "configs", "logs", "status"]

  [outputs.heartbeat.status]
    ok = "metrics > 0 && log_errors == 0"
    warn = "log_errors > 0 || (has(outputs.influxdb_v2) && outputs.influxdb_v2.exists(o, o.buffer_fullness > 0.8))"
    fail = "log_errors > 5 && has(outputs.influxdb_v2) && outputs.influxdb_v2.exists(o, o.buffer_fullness > 0.9)"
    order = ["fail", "warn", "ok"]
    default = "ok"

For more examples including buffer health, plugin-specific checks, and time-based expressions, see CEL expression examples.

View an agent’s status

1. In Telegraf Controller, go to Agents.
2. Check the Status column for each agent.
3. To see more details, click the More button (⋮) and select View Details.
4. The details page shows the reported status, reporting rule assignment, and the time of the last heartbeat.