Use Telegraf configurations

Use Telegraf Controller to centralize management of your Telegraf configurations and keep your agents consistent across environments. Apply the configuration by pointing your agents to the configuration URL.

• Apply a configuration to an agent
• Set dynamic values
  • Set parameter values
  • Set environment variables
• Auto-update agents
• Use Telegraf Controller to build commands

Apply a configuration to an agent

When starting a Telegraf agent, use a --config flag with the Telegraf Controller configuration TOML API URL—for example:

telegraf \
  --config "http://localhost:8888/api/configs/xxxxxx/toml"

Telegraf retrieves and validates the configuration from Telegraf Controller and then starts the telegraf process using the loaded configuration.

Set dynamic values

Telegraf and Telegraf Controller let you dynamically set values in your configuration files using parameters, environment variables, and secrets.

• Set parameter values
• Set environment variables

Set parameter values

Configuration parameters use the &{param_name[:default_value]} syntax in TOML configurations. Use URL-encoded query parameters in your configuration URL to define parameter values—for example:

Configuration TOML with a parameter

[[outputs.heartbeat]]
  instance_id = "&{agent_id}"
  # ...

Set the parameter value in the configuration URL

telegraf \
  --config "http://localhost:8888/api/configs/xxxxxx/toml?agent_id=my-agent-123"

Set environment variables

Telegraf environment variables use the ${VAR_NAME[:-default_value]} syntax in TOML configurations. Set environment variable values in the Telegraf agent’s environment before starting Telegraf—for example:

Configuration TOML with an environment variable

[[inputs.http]]
  urls = ["http://localhost:8080/metrics"]

  [inputs.http.headers]
    Authorization = "Bearer ${AUTH_TOKEN}"

Set the environment variable before starting Telegraf

AUTH_TOKEN=x00x0xx00xxxX0xXXx0000xxxX000x00XXxXx

telegraf \
  --config "http://localhost:8888/api/configs/xxxxxx/toml"

Auto-update agents

For agents to automatically recognize and load updates to their configuration, include the --config-url-watch-interval with a duration value that specifies how often the agent should check for updates—for example:

telegraf \
  --config https://locahost:8888/api/configs/xxxxxx/toml \
  --config-url-watch-interval 1h

In this example, the agent will check for configuration changes every hour and automatically reload the configuration if the configuration has been updated.

Use Telegraf Controller to build commands

Telegraf Controller provides a tool for building telegraf commands using parameters, environment variables, auto-update functionality, and Telegraf label selectors. To use this tool:

1. In the Telegraf Controller web interface, select Configurations in the navigation bar.

2. Click the name of the configuration you want to use.

3. Click Use this Configuration to open the modal window.

   

4. Define dynamic values and select options for your command:

   • Set environment variable values
   • Set parameter values
   • Enable automatic configuration updates and specify the check interval
   • Add label selectors to run certain plugins based on configuration labels

5. Click Copy Commands to copy the contents of the codeblock to your clipboard. The tool provides commands for Linux, macOS, and Windows (PowerShell).

   Your browser may not allow the Copy Commands button to copy to your clipboard under the following conditions:

   • You’re using an IP or domain name other than 0.0.0.0 or localhost and
   • You’re using HTTP, not HTTPS