Configure Telegraf

Telegraf uses a TOML configuration file to define which plugins to enable and which settings to use when Telegraf starts. To be valid, a configuration must define at least one input plugin and at least one output plugin.

See Get started to quickly get up and running with Telegraf.

The following pages cover each configuration topic in depth:

Telegraf configuration file

Learn the structure of the Telegraf configuration file, how to generate one, where Telegraf looks for configuration, and how to load configuration from multiple files or a remote URL.

TOML syntax for Telegraf

Learn the TOML configuration language details that matter for Telegraf configurations: table types, ordering pitfalls, string escaping, and duration values.

Telegraf agent settings

Reference for every setting in the Telegraf [agent] configuration table, grouped by what it controls: scheduling, batching and buffering, flushing, logging, host identity, pipeline behavior, and state persistence.

Common Telegraf plugin options

Reference for configuration options shared by Telegraf plugins of each type: naming instances, per-plugin intervals, measurement renaming, extra tags, execution order, and startup error behavior.

Filter Telegraf metrics

Use metric filters on any Telegraf plugin to select which metrics a plugin handles and which tags and fields remain: namepass, namedrop, tagpass, tagdrop, metricpass, fieldinclude, fieldexclude, taginclude, and tagexclude.

Use environment variables in Telegraf configurations

Substitute environment variables anywhere in the Telegraf configuration file with ${VAR} syntax, including shell parameter expansion forms for defaults and required variables.

Use secrets in Telegraf configurations

Keep credentials out of plain-text Telegraf configuration files: configure secret store plugins and reference secrets with @{store_id:secret_name} syntax.

Configure TLS for Telegraf plugins

Reference for the standard TLS options that Telegraf plugins provide: client and server certificate configuration, mutual TLS, cipher suites, and TLS version constraints.

Select Telegraf plugins with labels and selectors

Enable or disable Telegraf plugin instances at startup by adding labels to plugin definitions and passing selectors with the –select flag.

The rest of this page is a quick reference that maps the parts of a configuration file to the pages that document them.

Generate a configuration file

The telegraf config command creates a configuration file with plugins you select:

telegraf --input-filter cpu:mem --output-filter influxdb_v3 config > telegraf.conf

See Generate a configuration file and the telegraf config command.

Configuration file locations

Telegraf loads configuration from the path in the --config flag, the TELEGRAF_CONFIG_PATH environment variable, or a default location for your operating system. Load additional files with --config-directory, and load remote configuration by passing a URL to --config.

See Configuration file locations and Load configuration from a URL.

Set environment variables

Reference environment variables anywhere in the configuration file with ${VARIABLE_NAME} syntax. See Use environment variables.

Secret stores

Keep credentials out of plain-text configuration files with secret store plugins, and reference secrets as @{store_id:secret_key}.

Secret-store secrets

Plugin options that support secrets accept the @{store_id:secret_key} syntax. See Store secrets for configuring secret stores, referencing secrets, and managing them with the telegraf secrets command.

Global tags

Define tags in the [global_tags] table in key = "value" format. Telegraf applies global tags to all metrics gathered on the host. See the configuration file anatomy.

Agent configuration

The [agent] table controls collection intervals, batching and buffering, flushing, logging, and other agent-wide behavior. See Agent settings for every setting with types and defaults.

Intervals

Scheduling settings, including interval, round_interval, collection_jitter, collection_offset, flush_interval, and flush_jitter, control when Telegraf collects and writes metrics. See Collection scheduling in the agent settings reference.

Plugins

Enable a plugin by adding its TOML table to the configuration file, for example [[inputs.cpu]] or [[outputs.influxdb_v3]]. You can define multiple instances of any plugin. Each plugin’s specific options are documented in the Plugin directory, and all plugins share a set of common options such as alias, interval, name_override, and tags.

Input configuration

Input plugins collect metrics. See Collect data with input plugins and input plugin options.

Output configuration

Output plugins write metrics to destinations. See Write data with output plugins and output plugin options.

Processor configuration

Processor plugins transform metrics as they pass through the pipeline. See Processors and aggregators and processor plugin options.

Aggregator configuration

Aggregator plugins produce windowed aggregate metrics. See Processors and aggregators and aggregator plugin options.

Metric filtering

Metric filters attach to any plugin and control which metrics that plugin handles. See Filter metrics for the full reference and worked examples.

Filters

Selectors

Selectors decide whether a plugin handles a metric: namepass, namedrop, tagpass, tagdrop, and metricpass. See Selectors.

Modifiers

Modifiers decide which tags and fields remain on a metric: fieldinclude, fieldexclude, taginclude, and tagexclude. See Modifiers.

Filtering examples

For complete worked examples of every filter option, see filtering examples.

Plugin selection via labels and selectors

Label plugin instances in the configuration file and use the --select flag to enable only matching plugins at startup. See Labels and selectors.

Was this page helpful?

Thank you for your feedback!