docs-v2/content/telegraf/controller/agents/create.md

title	list_title	description	menu	weight
Create agents in Telegraf Controller	Create agents	Learn how Telegraf Controller creates agents from heartbeat plugin reports and how to verify new agents in the UI.	telegraf_controller name parent Create agents Manage agents	101

Agents represent Telegraf instances that send heartbeat data to {{% product-name %}} through the heartbeat output plugin. {{% product-name "short" %}} 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 {{% product-name %}} 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, {{% product-name %}} 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 {{% product-name %}}. The following heartbeat plugin configuration options are available:

• url: ({{% req %}}) URL of heartbeat endpoint.
• instance_id: ({{% req %}}) Unique identifier for the Telegraf instance or agent (also known as the agent ID).
• token: ({{% req text="Required with auth enabled" %}}) {{% product-name %}} 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: ({{% req text="Recommended" color="magenta" %}}) Agent metrics including number of metrics collected and written since the last heartbeat, logged error and warning counts, etc.
  • configs: ({{% req text="Recommended" color="magenta" %}}) 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.

{{% telegraf/dynamic-values %}}

[[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"

{{% /telegraf/dynamic-values %}}

[!Important]

Authorize heartbeats using an API token

If {{% product-name %}} requires authorization on the Heartbeat API, include the token option in your heartbeat plugin configuration. Provide a {{% product-name %}} token with write permissions on the Heartbeat API.

We recommend defining the INFLUX_TOKEN environment variable when starting Telegraf and using that to define the token in your heartbeat plugin.

Verify a new agent

1. Open {{% product-name %}} and go to Agents.
2. Confirm the agent appears in the list with the expected instance_id.
3. Click the More button ({{% icon "tc-more" %}}) and select View Details to verify metadata, labels, and the reporting rule assignment.