Create a Telegraf configuration
Create a configuration to define how Telegraf collects, processes, and writes metrics. Telegraf Controller stores the configuration as TOML that you can use across agents. Upload existing configurations, write raw TOML in the Code Editor, or use the Telegraf Builder visual interface to manage and configure plugins.
Create a configuration
- In the Telegraf Controller web interface, select Configurations in the navigation bar.
- Click Add Config.
- Enter a configuration name and optional description.
Names are unique among configurations, matched exactly including case,
and can be up to 255 characters.
If the name is already taken, Telegraf Controller reports
Configuration "<name>" already existsand the dialog stays open. Through the API, the create request returns409 Conflictwith"error": "config_name_taken". A configuration and a configuration group can share a name. Descriptions can be up to 1,000 characters and support Markdown. See Format a description with Markdown. - (Optional) To assign aliases to the configuration, click Add Alias and enter an alias that follows the naming rules.
- Use the Telegraf Controller Code Editor or Telegraf Builder to provide or build the Telegraf configuration TOML.
- Click Create Configuration.
When you create a configuration, Telegraf Controller records it as the first version in the configuration’s version history.
Use the Code Editor
The Telegraf Controller Code Editor is an in-browser TOML editor that lets you upload or manually write Telegraf configuration TOML.
For detailed information about using the Code Editor, see Use the Code Editor.

Use the Telegraf Builder
The Telegraf Builder is a visual interface for adding and configuring Telegraf plugins in a Telegraf configuration. The Telegraf Builder is currently a beta feature.
For detailed information about using the Telegraf Builder, see Use the Telegraf Builder.

The Telegraf Builder does not support all Telegraf plugins
We are in the process of adding support for more Telegraf plugins in the Telegraf Builder. You can use plugins that are not currently supported by the builder, but you must add and edit them with the Code Editor.
Format a description with Markdown
Configuration descriptions support Markdown. The description editor has two tabs: Write, where you type the description, and Preview, which shows how Telegraf Controller renders it. A counter under the field shows the length of the description against the 1,000-character limit.
Telegraf Controller renders standard Markdown without extensions:
- Headings, paragraphs, and blockquotes
- Bulleted and numbered lists
- Bold, italic, and inline code
- Fenced code blocks
- Links, which open in a new browser tab
A single line break in the editor renders as a line break.
Tables, task lists, and strikethrough are not supported.
Raw HTML appears as literal text, images are replaced with their alternative
text, and links with unsafe URL schemes such as javascript: are removed.
The configuration detail page renders the full description. Where a description appears on a single line, only bold, italic, and inline code formatting is kept, and headings, lists, and links are shown as plain text. Single-line descriptions appear in the configuration list, in page headers, in the Agent Configurations card on an agent detail page, and in the dialogs for adding configurations to a group.
Heartbeat output plugin
When adding a configuration, Telegraf Controller prepopulates the configuration with a Telegraf heartbeat output plugin. This plugin reports agent information back to the Telegraf Controller heartbeat API and lets you monitor the health of your deployed Telegraf agents.
[[outputs.heartbeat]]
url = "http://localhost:8000/agents/heartbeat"
instance_id = "&{agent_id}"
interval = "1m"
include = ["hostname", "statistics", "configs"]
token = "${TELEGRAF_CONTROLLER_TOKEN}"To monitor agents with Telegraf Controller, include a heartbeat plugin in your Telegraf configurations.
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.
Next steps
- Substitute values to keep configurations portable across environments.
- Apply the configuration to your Telegraf agents.
Was this page helpful?
Thank you for your feedback!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for Telegraf Controller and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support.