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
• Configure agents
• Verify a new 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 = "${INFLUX_TOKEN}"
  interval = "1m"
  include = ["hostname", "statistics", "configs"]

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

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.