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.
  • logs: A sample of recent Telegraf logs, shown on the agent detail page. See Include logs with heartbeats.
  • status: The agent’s self-evaluated status. See Set agent statuses.
• 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"

Report the agent IP address from behind a proxy

Telegraf Controller records the IP address a heartbeat arrives from. When an agent connects through a proxy, NAT gateway, or load balancer, that address belongs to the intermediary, not to the agent.

To report the agent’s real address, send it in the Telegraf-Agent-IP header using the heartbeat plugin’s headers option:

[[outputs.heartbeat]]
  url = "http://telegraf_controller.example.com/agents/heartbeat"
  instance_id = "&{agent_id}"

  [outputs.heartbeat.headers]
    Telegraf-Agent-IP = "203.0.113.7"

Telegraf Controller honors the header only when it is sent exactly once and its value parses as a valid IPv4 or IPv6 address (at most 45 characters, no zone IDs or address lists). Otherwise, it falls back to the connection’s peer address. The header name is case-insensitive.

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.