Create agents in Telegraf Controller

Agents represent Telegraf instances that send heartbeat data to Telegraf Controller through the heartbeat output plugin. Controller uses the heartbeat payload to create and track each agent.

How agent creation works

  • The heartbeat output plugin in a Telegraf configuration reports agent data back to the /agents/heartbeat endpoint of your Telegraf Controller instance.
  • The heartbeat payload includes a unique instance_id (also referred to as an “agent ID”) for the agent.
  • When the first heartbeat arrives for an agent, Telegraf Controller automatically creates the agent record and marks it with the reported status. Subsequent agent heartbeats update the existing agent record.

Configure agents

Heartbeat output plugin configuration options determine what agent data Telegraf sends to Telegraf Controller. The following heartbeat plugin configuration options are available:

  • url: (Required) URL of heartbeat endpoint.
  • instance_id: (Required) Unique identifier for the Telegraf instance or agent (also known as the agent ID).
  • token: (Required with auth enabled) Telegraf Controller API token for the heartbeat endpoint. The token must have write permissions on the Heartbeat API.
  • interval: Interval for sending heartbeat messages. Default is 1m (every minute).
  • include: Information to include in the heartbeat message. Available options are:
    • hostname: Hostname of the machine running Telegraf.
    • statistics: (Recommended) Agent metrics including number of metrics collected and written since the last heartbeat, logged error and warning counts, etc.
    • configs: (Recommended) Redacted list of configurations loaded by the Telegraf instance.
  • headers: HTTP headers to include with the heartbeat request.

Example heartbeat output plugin

The following is an example heartbeat output plugin configuration that uses an agent_id configuration parameter to specify the instance_id.

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

  [outputs.heartbeat.headers]
    User-Agent = "telegraf"

Authorize heartbeats using an API token

If Telegraf Controller requires authorization on the Heartbeat API, include the token option in your heartbeat plugin configuration. Provide a Telegraf Controller token with write permissions on the Heartbeat API.

We recommend defining the TELEGRAF_CONTROLLER_TOKEN environment variable when starting Telegraf and using it to define the token in your heartbeat plugin. On Telegraf 1.38.x or earlier, use INFLUX_TOKEN instead. For details, see Use API tokens.

Verify a new agent

  1. Open Telegraf Controller and go to Agents.
  2. Confirm the agent appears in the list with the expected instance_id.
  3. Click the More button (⋮) and select View Details to verify metadata, labels, and the reporting rule assignment.

Was this page helpful?

Thank you for your feedback!