---
title: Configure Telegraf
description: 'Overview of the Telegraf configuration file: generating and loading configuration, agent settings, plugin options, metric filtering, and environment variables.'
url: https://docs.influxdata.com/telegraf/v1/configuration/
estimated_tokens: 1972
product: Telegraf Enterprise
version: v1
publisher: InfluxData
canonical: https://docs.influxdata.com/telegraf/v1/configuration/
date: '2026-08-14T12:27:55-06:00'
lastmod: '2026-08-14T12:27:55-06:00'
---

Telegraf uses a [TOML](/telegraf/v1/configuration/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.

> [!Note]
> See [Get started](/telegraf/v1/get-started/) to quickly get up and
> running with Telegraf.

The following pages cover each configuration topic in depth:

### [Telegraf configuration file](/telegraf/v1/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](/telegraf/v1/configuration/toml/)

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

### [Telegraf agent settings](/telegraf/v1/configuration/agent/)

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](/telegraf/v1/configuration/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](/telegraf/v1/configuration/filtering/)

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](/telegraf/v1/configuration/environment-variables/)

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](/telegraf/v1/configuration/secrets/)

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](/telegraf/v1/configuration/tls/)

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](/telegraf/v1/configuration/labels-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:

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

See [Generate a configuration file](/telegraf/v1/configuration/file/#generate-a-configuration-file)and the [telegraf config command](/telegraf/v1/commands/config/).

## 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](/telegraf/v1/configuration/file/#configuration-file-locations)and [Load configuration from a URL](/telegraf/v1/configuration/file/#load-configuration-from-a-url).

## Set environment variables

Reference environment variables anywhere in the configuration file with`${VARIABLE_NAME}` syntax.
See [Use environment variables](/telegraf/v1/configuration/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](/telegraf/v1/configuration/secrets/) for configuring
secret stores, referencing secrets, and managing them with the[telegraf secrets command](/telegraf/v1/commands/secrets/).

## 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](/telegraf/v1/configuration/file/).

## Agent configuration

The `[agent]` table controls collection intervals, batching and buffering,
flushing, logging, and other agent-wide behavior.
See [Agent settings](/telegraf/v1/configuration/agent/) 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](/telegraf/v1/configuration/agent/#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](/telegraf/v1/plugins/), and all plugins share a set of[common options](/telegraf/v1/configuration/plugin-options/) such as`alias`, `interval`, `name_override`, and `tags`.

### Input configuration

Input plugins collect metrics.
See [Collect data with input plugins](/telegraf/v1/configure_plugins/input_plugins/)and [input plugin options](/telegraf/v1/configuration/plugin-options/#input-plugin-options).

### Output configuration

Output plugins write metrics to destinations.
See [Write data with output plugins](/telegraf/v1/configure_plugins/output_plugins/)and [output plugin options](/telegraf/v1/configuration/plugin-options/#output-plugin-options).

### Processor configuration

Processor plugins transform metrics as they pass through the pipeline.
See [Processors and aggregators](/telegraf/v1/configure_plugins/aggregator_processor/)and [processor plugin options](/telegraf/v1/configuration/plugin-options/#processor-plugin-options).

### Aggregator configuration

Aggregator plugins produce windowed aggregate metrics.
See [Processors and aggregators](/telegraf/v1/configure_plugins/aggregator_processor/)and [aggregator plugin options](/telegraf/v1/configuration/plugin-options/#aggregator-plugin-options).

## Metric filtering

Metric filters attach to any plugin and control which metrics that plugin
handles.
See [Filter metrics](/telegraf/v1/configuration/filtering/) 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](/telegraf/v1/configuration/filtering/#selectors).

#### Modifiers

Modifiers decide which tags and fields remain on a metric: `fieldinclude`,`fieldexclude`, `taginclude`, and `tagexclude`.
See [Modifiers](/telegraf/v1/configuration/filtering/#modifiers).

### Filtering examples

For complete worked examples of every filter option, see[filtering examples](/telegraf/v1/configuration/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](/telegraf/v1/configuration/labels-selectors/).

#### Related

* [Get started with Telegraf](/telegraf/v1/get-started/)
* [The Telegraf data pipeline](/telegraf/v1/concepts/data-pipeline/)