78 lines
3.0 KiB
Markdown
78 lines
3.0 KiB
Markdown
---
|
|
title: Create agents in Telegraf Controller
|
|
list_title: Create agents
|
|
description: >
|
|
Learn how Telegraf Controller creates agents from heartbeat plugin reports
|
|
and how to verify new agents in the UI.
|
|
menu:
|
|
telegraf_controller:
|
|
name: Create agents
|
|
parent: Manage agents
|
|
weight: 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.
|
|
|
|
<!-- TOC -->
|
|
- [How agent creation works](#how-agent-creation-works)
|
|
- [Configure agents](#configure-agents)
|
|
- [Verify a new agent](#verify-a-new-agent)
|
|
<!-- /TOC -->
|
|
|
|
## How agent creation works
|
|
|
|
- The [heartbeat output plugin](/telegraf/v1/output-plugins/heartbeat/) 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](/telegraf/v1/output-plugins/heartbeat/) 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**: Authorization token for the heartbeat endpoint
|
|
- **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`.
|
|
|
|
```toml
|
|
[[outputs.heartbeat]]
|
|
url = "http://telegraf_controller.example.com/agents/heartbeat"
|
|
instance_id = "&{agent_id}"
|
|
interval = "1m"
|
|
include = ["hostname", "statistics", "configs"]
|
|
|
|
[outputs.heartbeat.headers]
|
|
User-Agent = "telegraf"
|
|
```
|
|
|
|
## 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.
|