Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

chore(telegraf): update telegraf configuration doc (#6517) 

* chore(telegraf): update telegraf configuration doc, closes #6448

* Apply suggestions from code review

Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>

---------

Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>
pull/6519/head
Scott Anderson 2025-11-07 15:50:09 -07:00 committed by GitHub
parent 07bfb6f8cd
commit 08bc79ff3e
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 432 additions and 164 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
.husky/_/pre-commit
View File

@ -33,9 +33,6 @@ call_lefthook()
then then
"$dir/node_modules/lefthook/bin/index.js" "$@" "$dir/node_modules/lefthook/bin/index.js" "$@"
elif go tool lefthook -h >/dev/null 2>&1
then
go tool lefthook "$@"
elif bundle exec lefthook -h >/dev/null 2>&1 elif bundle exec lefthook -h >/dev/null 2>&1
then then
bundle exec lefthook "$@" bundle exec lefthook "$@"
@ -45,21 +42,12 @@ call_lefthook()
elif pnpm lefthook -h >/dev/null 2>&1 elif pnpm lefthook -h >/dev/null 2>&1
then then
pnpm lefthook "$@" pnpm lefthook "$@"
elif swift package lefthook >/dev/null 2>&1 elif swift package plugin lefthook >/dev/null 2>&1
then then
swift package --build-path .build/lefthook --disable-sandbox lefthook "$@" swift package --disable-sandbox plugin lefthook "$@"
elif command -v mint >/dev/null 2>&1 elif command -v mint >/dev/null 2>&1
then then
mint run csjones/lefthook-plugin "$@" mint run csjones/lefthook-plugin "$@"
elif uv run lefthook -h >/dev/null 2>&1
then
uv run lefthook "$@"
elif mise exec -- lefthook -h >/dev/null 2>&1
then
mise exec -- lefthook "$@"
elif devbox run lefthook -h >/dev/null 2>&1
then
devbox run lefthook "$@"
else else
echo "Can't find lefthook in PATH" echo "Can't find lefthook in PATH"
fi fi

16
.husky/_/pre-push
View File

@ -33,9 +33,6 @@ call_lefthook()
then then
"$dir/node_modules/lefthook/bin/index.js" "$@" "$dir/node_modules/lefthook/bin/index.js" "$@"
elif go tool lefthook -h >/dev/null 2>&1
then
go tool lefthook "$@"
elif bundle exec lefthook -h >/dev/null 2>&1 elif bundle exec lefthook -h >/dev/null 2>&1
then then
bundle exec lefthook "$@" bundle exec lefthook "$@"
@ -45,21 +42,12 @@ call_lefthook()
elif pnpm lefthook -h >/dev/null 2>&1 elif pnpm lefthook -h >/dev/null 2>&1
then then
pnpm lefthook "$@" pnpm lefthook "$@"
elif swift package lefthook >/dev/null 2>&1 elif swift package plugin lefthook >/dev/null 2>&1
then then
swift package --build-path .build/lefthook --disable-sandbox lefthook "$@" swift package --disable-sandbox plugin lefthook "$@"
elif command -v mint >/dev/null 2>&1 elif command -v mint >/dev/null 2>&1
then then
mint run csjones/lefthook-plugin "$@" mint run csjones/lefthook-plugin "$@"
elif uv run lefthook -h >/dev/null 2>&1
then
uv run lefthook "$@"
elif mise exec -- lefthook -h >/dev/null 2>&1
then
mise exec -- lefthook "$@"
elif devbox run lefthook -h >/dev/null 2>&1
then
devbox run lefthook "$@"
else else
echo "Can't find lefthook in PATH" echo "Can't find lefthook in PATH"
fi fi

16
.husky/_/prepare-commit-msg
View File

@ -33,9 +33,6 @@ call_lefthook()
then then
"$dir/node_modules/lefthook/bin/index.js" "$@" "$dir/node_modules/lefthook/bin/index.js" "$@"
elif go tool lefthook -h >/dev/null 2>&1
then
go tool lefthook "$@"
elif bundle exec lefthook -h >/dev/null 2>&1 elif bundle exec lefthook -h >/dev/null 2>&1
then then
bundle exec lefthook "$@" bundle exec lefthook "$@"
@ -45,21 +42,12 @@ call_lefthook()
elif pnpm lefthook -h >/dev/null 2>&1 elif pnpm lefthook -h >/dev/null 2>&1
then then
pnpm lefthook "$@" pnpm lefthook "$@"
elif swift package lefthook >/dev/null 2>&1 elif swift package plugin lefthook >/dev/null 2>&1
then then
swift package --build-path .build/lefthook --disable-sandbox lefthook "$@" swift package --disable-sandbox plugin lefthook "$@"
elif command -v mint >/dev/null 2>&1 elif command -v mint >/dev/null 2>&1
then then
mint run csjones/lefthook-plugin "$@" mint run csjones/lefthook-plugin "$@"
elif uv run lefthook -h >/dev/null 2>&1
then
uv run lefthook "$@"
elif mise exec -- lefthook -h >/dev/null 2>&1
then
mise exec -- lefthook "$@"
elif devbox run lefthook -h >/dev/null 2>&1
then
devbox run lefthook "$@"
else else
echo "Can't find lefthook in PATH" echo "Can't find lefthook in PATH"
fi fi

548
content/telegraf/v1/configuration.md
View File

@ -16,9 +16,8 @@ settings to use when Telegraf starts.
Each Telegraf plugin has its own set of configuration options. Each Telegraf plugin has its own set of configuration options.
Telegraf also provides global options for configuring specific Telegraf settings. Telegraf also provides global options for configuring specific Telegraf settings.
{{% note %}} > [!Note]
See [Get started](/telegraf/v1/get_started/) to quickly get up and running with Telegraf. > See [Get started](/telegraf/v1/get_started/) to quickly get up and running with Telegraf.
{{% /note %}}
## Generate a configuration file ## Generate a configuration file
@ -26,6 +25,7 @@ The `telegraf config` command lets you generate a configuration file using Teleg
- [Create a configuration with default input and output plugins](#create-a-configuration-with-default-input-and-output-plugins) - [Create a configuration with default input and output plugins](#create-a-configuration-with-default-input-and-output-plugins)
- [Create a configuration with specific input and output plugins](#create-a-configuration-with-specific-input-and-output-plugins) - [Create a configuration with specific input and output plugins](#create-a-configuration-with-specific-input-and-output-plugins)
- [Windows PowerShell v5 encoding](#windows-powershell-v5-encoding)
### Create a configuration with default input and output plugins ### Create a configuration with default input and output plugins
@ -118,6 +118,23 @@ config > telegraf.conf
For more advanced configuration details, see the For more advanced configuration details, see the
[configuration documentation](/telegraf/v1/administration/configuration/). [configuration documentation](/telegraf/v1/administration/configuration/).
### Windows PowerShell v5 encoding
In PowerShell 5, the default encoding is UTF-16LE and not UTF-8.
Telegraf expects a valid UTF-8 file.
This is not an issue with PowerShell 6 or newer, as well as the Command Prompt
or with using the Git Bash shell.
When using PowerShell 5 or earlier, specify the output encoding when generating
a full configuration file:
```powershell
telegraf.exe config | Out-File -Encoding utf8 telegraf.conf
```
This will generate a UTF-8 encoded file with a byte-order mark (BOM).
However, Telegraf correctly handles the leading BOM.
## Configuration file locations ## Configuration file locations
When starting Telegraf, use the `--config` flag to specify the configuration file location: When starting Telegraf, use the `--config` flag to specify the configuration file location:
@ -136,62 +153,91 @@ Telegraf processes each configuration file separately, and
the effective configuration is the union of all the files. the effective configuration is the union of all the files.
If any file isn't a valid configuration, Telegraf returns an error. If any file isn't a valid configuration, Telegraf returns an error.
{{% warn %}} > [!Warning]
> #### Telegraf doesn't support partial configurations
#### Telegraf doesn't support partial configurations >
> Telegraf doesn't concatenate configuration files before processing them.
Telegraf doesn't concatenate configuration files before processing them. > Each configuration file that you provide must be a valid configuration.
Each configuration file that you provide must be a valid configuration. >
> If you want to use separate files to manage a configuration, you can use your
If you want to use separate files to manage a configuration, you can use your > own custom code to concatenate and pre-process the files, and then provide the
own custom code to concatenate and pre-process the files, and then provide the > complete configuration to Telegraf--for example:
complete configuration to Telegraf--for example: >
> 1. Configure plugin sections and assign partial configs a file extension different
1. Configure plugin sections and assign partial configs a file extension different > from `.conf` to prevent Telegraf loading them--for example:
from `.conf` to prevent Telegraf loading them--for example: >
> ```toml
```toml > # main.opcua: Main configuration file
# main.opcua: Main configuration file > ...
... > [[inputs.opcua_listener]]
[[inputs.opcua_listener]] > name = "PluginSection"
name = "PluginSection" > endpoint = "opc.tcp://10.0.0.53:4840"
endpoint = "opc.tcp://10.0.0.53:4840" > ...
... > ```
``` >
> ```toml
```toml > # group_1.opcua
# group_1.opcua > [[inputs.opcua_listener.group]]
[[inputs.opcua_listener.group]] > name = "SubSection1"
name = "SubSection1" > ...
... > ```
``` >
> ```toml
```toml > # group_2.opcua
# group_2.opcua > [[inputs.opcua_listener.group]]
[[inputs.opcua_listener.group]] > name = "SubSection2"
name = "SubSection2" > ...
... > ```
``` >
> 2. Before you start Telegraf, run your custom script to concatenate
2. Before you start Telegraf, run your custom script to concatenate `main.opcua`, `group_1.opcua`, `main.opcua`, `group_1.opcua`,
`group_2.opcua` into a valid `telegraf.conf`. > `group_2.opcua` into a valid `telegraf.conf`.
3. Start Telegraf with the complete, valid `telegraf.conf` configuration. > 3. Start Telegraf with the complete, valid `telegraf.conf` configuration.
{{% /warn %}}
## Set environment variables ## Set environment variables
Use environment variables anywhere in the configuration file by enclosing them in `${}`. Use environment variables anywhere in the configuration file by enclosing them in `${}`.
For strings, variables must be in quotes (for example, `"test_${STR_VAR}"`). For strings, variables must be in quotes (for example, `"test_${STR_VAR}"`).
For numbers and Booleans, variables must be unquoted (for example, `${INT_VAR}`, `${BOOL_VAR}`). For numbers and booleans, variables must be unquoted (for example, `${INT_VAR}`,
`${BOOL_VAR}`).
You can also set environment variables using the Linux `export` command: `export password=mypassword` When using double quotes, escape any backslashes (for example: `"C:\\Program Files"`) or
other special characters.
If using an environment variable with a single backslash, enclose the variable
in single quotes to signify a string literal (for example:
`'C:\Program Files'`).
Telegraf also supports Shell parameter expansion for environment variables which
allows the following:
- `${VARIABLE:-default}`: evaluates to `default` if `VARIABLE` is unset or empty
in the environment.
- `${VARIABLE-default}`: evaluates to `default` only if `VARIABLE` is unset in
the environment. Similarly, the following syntax allows you to specify
mandatory variables:
- `${VARIABLE:?err}`: exits with an error message containing `err` if `VARIABLE`
is unset or empty in the environment.
- `${VARIABLE?err}`: exits with an error message containing `err` if `VARIABLE`
is unset in the environment.
When using the `.deb` or `.rpm` packages, you can define environment variables
in the `/etc/default/telegraf` file.
You can also set environment variables using the Linux `export` command:
<!--pytest.mark.skip-->
```bash
export password=mypassword
```
> **Note:** Use a secret store or environment variables to store sensitive credentials. > **Note:** Use a secret store or environment variables to store sensitive credentials.
### Example: Telegraf environment variables ### Example: Telegraf environment variables
Set environment variables in the Telegraf environment variables file (`/etc/default/telegraf`)--for example: Set environment variables in the Telegraf environment variables file
(`/etc/default/telegraf`).
#### For InfluxDB 1.x:
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
@ -199,7 +245,31 @@ Set environment variables in the Telegraf environment variables file (`/etc/defa
USER="alice" USER="alice"
INFLUX_URL="http://localhost:8086" INFLUX_URL="http://localhost:8086"
INFLUX_SKIP_DATABASE_CREATION="true" INFLUX_SKIP_DATABASE_CREATION="true"
INFLUX_PASSWORD="monkey123" INFLUX_PASSWORD="passw0rd123"
```
#### For InfluxDB OSS v2:
<!--pytest.mark.skip-->
```sh
INFLUX_HOST="http://localhost:8086"
INFLUX_TOKEN="replace_with_your_token"
INFLUX_ORG="your_username"
INFLUX_BUCKET="replace_with_your_bucket_name"
```
#### For InfluxDB Cloud Serverless:
<!--pytest.mark.skip-->
```sh
# For AWS West (Oregon)
INFLUX_HOST="https://us-west-2-1.aws.cloud2.influxdata.com"
# Other Cloud URLs at https://docs.influxdata.com/influxdb/cloud/reference/regions/
INFLUX_TOKEN="replace_with_your_token"
INFLUX_ORG="yourname@yourcompany.com"
INFLUX_BUCKET="replace_with_your_bucket_name"
``` ```
In the Telegraf configuration file (`/etc/telegraf.conf`), reference the variables--for example: In the Telegraf configuration file (`/etc/telegraf.conf`), reference the variables--for example:
@ -210,10 +280,25 @@ In the Telegraf configuration file (`/etc/telegraf.conf`), reference the variabl
[[inputs.mem]] [[inputs.mem]]
# For InfluxDB 1.x:
[[outputs.influxdb]] [[outputs.influxdb]]
urls = ["${INFLUX_URL}"] urls = ["${INFLUX_URL}"]
skip_database_creation = ${INFLUX_SKIP_DATABASE_CREATION} skip_database_creation = ${INFLUX_SKIP_DATABASE_CREATION}
password = "${INFLUX_PASSWORD}" password = "${INFLUX_PASSWORD}"
# For InfluxDB OSS 2:
[[outputs.influxdb_v2]]
urls = ["${INFLUX_HOST}"]
token = "${INFLUX_TOKEN}"
organization = "${INFLUX_ORG}"
bucket = "${INFLUX_BUCKET}"
# For InfluxDB Cloud:
[[outputs.influxdb_v2]]
urls = ["${INFLUX_HOST}"]
token = "${INFLUX_TOKEN}"
organization = "${INFLUX_ORG}"
bucket = "${INFLUX_BUCKET}"
``` ```
When Telegraf runs, the effective configuration is the following: When Telegraf runs, the effective configuration is the following:
@ -222,68 +307,174 @@ When Telegraf runs, the effective configuration is the following:
[global_tags] [global_tags]
user = "alice" user = "alice"
# For InfluxDB 1.x:
[[outputs.influxdb]] [[outputs.influxdb]]
urls = "http://localhost:8086" urls = ["http://localhost:8086"]
skip_database_creation = true skip_database_creation = true
password = "monkey123" password = "passw0rd123"
# For InfluxDB OSS 2:
[[outputs.influxdb_v2]]
urls = ["http://localhost:8086"]
token = "replace_with_your_token"
organization = "your_username"
bucket = "replace_with_your_bucket_name"
# For InfluxDB Cloud:
[[outputs.influxdb_v2]]
urls = ["https://us-west-2-1.aws.cloud2.influxdata.com"]
token = "replace_with_your_token"
organization = "yourname@yourcompany.com"
bucket = "replace_with_your_bucket_name"
``` ```
## Secret stores
Telegraf also supports secret stores for providing credentials or similar.
Configure one or more secret store plugins and then reference the secret in
your plugin configurations.
Reference secrets using the following syntax:
```txt
@{<secret_store_id>:<secret_name>}
```
- `secret_store_id`: the unique ID you define for your secret store plugin.
- `secret_name`: the name of the secret to use.
> [!Note]
> Both and `secret_store_id` and `secret_name` only support alphanumeric
> characters and underscores.
### Example: Use secret stores
This example illustrates the use of secret stores in plugins:
```toml
[global_tags]
user = "alice"
[[secretstores.os]]
id = "local_secrets"
[[secretstores.jose]]
id = "cloud_secrets"
path = "/etc/telegraf/secrets"
# Optional reference to another secret store to unlock this one.
password = "@{local_secrets:cloud_store_passwd}"
[[inputs.http]]
urls = ["http://server.company.org/metrics"]
username = "@{local_secrets:company_server_http_metric_user}"
password = "@{local_secrets:company_server_http_metric_pass}"
[[outputs.influxdb_v2]]
urls = ["https://us-west-2-1.aws.cloud2.influxdata.com"]
token = "@{cloud_secrets:influxdb_token}"
organization = "yourname@yourcompany.com"
bucket = "replace_with_your_bucket_name"
```
### Notes on secret stores
Not all plugins support secrets.
When using plugins that support secrets, Telegraf locks the memory pages
containing the secrets.
Therefore, the locked memory limit has to be set to a
suitable value.
Telegraf will check the limit and the number of used secrets at
startup and will warn if your limit is too low.
In this case, please increase
the limit via `ulimit -l`.
If you are running Telegraf in a jail you might need to allow locked pages in
that jail by setting `allow.mlock = 1;` in your config.
## Global tags ## Global tags
Global tags can be specified in the `[global_tags]` section of the configuration file Global tags can be specified in the `[global_tags]` section of the configuration
in `key="value"` format. file in `key="value"` format.
Telegraf applies the global tags to all metrics gathered on this host. Telegraf applies the global tags to all metrics gathered on this host.
## Agent configuration ## Agent configuration
The `[agent]` section contains the following configuration options: The `[agent]` section contains the following configuration options:
- **interval**: Default data collection interval for all inputs - **interval**: Default data collection interval for all inputs.
- **round_interval**: Rounds collection interval to `interval`. - **round_interval**: Rounds collection interval to `interval`.
For example, if `interval` is set to `10s`, then the agent collects on :00, :10, :20, etc. For example, if `interval` is set to `10s`, then the agent collects on :00, :10, :20, etc.
- **metric_batch_size**: Sends metrics to the output in batches of at - **metric_batch_size**: Telegraf sends metrics to outputs in batches of at
most `metric_batch_size` metrics. most `metric_batch_size` metrics.
- **metric_buffer_limit**: Caches `metric_buffer_limit` metrics This controls the size of writes that Telegraf sends to output plugins.
for each output, and flushes this buffer on a successful write. - **metric_buffer_limit**: Maximum number of unwritten metrics per output.
This should be a multiple of `metric_batch_size` and could not be less Increasing this value allows for longer periods of output downtime without
than 2 times `metric_batch_size`. dropping metrics at the cost of higher maximum memory usage.
- **collection_jitter**: Used to jitter the collection by a random amount. The oldest metrics are overwritten in favor of new ones when the buffer fills up.
Each plugin sleeps for a random time within jitter before collecting. - **collection_jitter**: Jitter the collection by a random interval.
This can be used to avoid many plugins querying things like **sysfs** at the Each plugin sleeps for a random time within the defined jitter before collecting.
Use this to avoid many plugins querying things like sysfs at the
same time, which can have a measurable effect on the system. same time, which can have a measurable effect on the system.
- **flush_interval**: Default data flushing interval for all outputs. - **collection_offset**: Shift the collection by the given interval.
Don't set this below `interval`. Use this to avoid many plugins querying constraint devices
Maximum `flush_interval` is `flush_interval` + `flush_jitter` at the same time by manually scheduling them in time.
- **flush_jitter**: Jitter the flush interval by a random amount. - **flush_interval**: Default flushing interval for all outputs.
This is primarily to avoid Maximum `flush_interval` is `flush_interval` + `flush_jitter`.
large write spikes for users running a large number of Telegraf instances. - **flush_jitter**: Default flush jitter for all outputs.
For example, a `flush_jitter` of `5s` and `flush_interval` of `10s` means This jitters the flush interval by a random amount.
flushes happen every 10-15s. This is primarily to avoid large write spikes for users
- **precision**: Collected metrics are rounded to the precision specified as an running a large number of Telegraf instances.
`interval` (integer + unit, ex: `1ns`, `1us`, `1ms`, and `1s` . Precision isn't For example, a jitter of `5s` and an interval of `10s` means flushes happen
used for service inputs, such as `logparser` and `statsd`. every 10-15 seconds.
- **debug**: Run Telegraf in debug mode. - **precision**: Round collected metrics to the precision specified as an interval.
- **quiet**: Run Telegraf in quiet mode (error messages only). Precision is _not_ used for service inputs.
- **logtarget**: Controls the destination for logs and can be set to `"file"`, It is up to each individual service input to set the timestamp at the appropriate precision.
`"stderr"`, or, on Windows, `"eventlog"`. - **debug**: Log at debug level.
When set to `"file"`, the output file is determined by the logfile setting. - **quiet**: Log only error level messages.
- **logfile**: If logtarget is set to `“file”`, specify the logfile name. - **logformat**: Log format controls the way messages are logged and can be one
If set to an empty string, then logs are written to stderr. of `text`, `structured` or, on Windows, `eventlog`.
- **logfile_rotation_interval**: Rotates the logfile after the time interval specified. The output file (if any) is determined by the `logfile` setting.
When set to `0`, no time-based rotation is performed. - **structured_log_message_key**: Message key for structured logs, to override
- **logfile_rotation_max_size**: Rotates logfile when it becomes larger than the the default of `msg`.
specified size. Ignored if `logformat` is not `structured`.
When set to `0`, no size-based rotation is performed. - **logfile**: Name of the file to be logged to or stderr if unset or empty.
This setting is ignored for the `eventlog` format.
- **logfile_rotation_interval**: The logfile rotates after the time interval specified.
When set to 0 no time based rotation is performed.
- **logfile_rotation_max_size**: The logfile rotates when it becomes larger than the specified size.
When set to 0 no size based rotation is performed.
- **logfile_rotation_max_archives**: Maximum number of rotated archives to keep, - **logfile_rotation_max_archives**: Maximum number of rotated archives to keep,
any older logs are deleted. any older logs are deleted.
If set to `-1`, no archives are removed. If set to -1, no archives are removed.
- **log_with_timezone**: Set a timezone to use when logging--for example, `"America/Chicago"`. - **log_with_timezone**: Pick a timezone to use when logging or type 'local' for local time.
To use local time, set to `"local"`. Example: 'America/Chicago'.
See [timezone options and formats](https://socketloop.com/tutorials/golang-display-list-of-timezones-with-gmt). [See this page for options/formats.](https://socketloop.com/tutorials/golang-display-list-of-timezones-with-gmt)
- **hostname**: Override default hostname, if empty use `os.Hostname()`. - **hostname**: Override the default hostname, if empty use `os.Hostname()`.
- **omit_hostname**: If true, do not set the `host` tag in the Telegraf agent. - **omit_hostname**: If set to true, do no set the "host" tag in the Telegraf agent.
- **skip_processors_after_aggregators**: If true, processors do not run again - **snmp_translator**: Method of translating SNMP objects.
after aggregators. Default is false. Can be "netsnmp" (deprecated) which translates by calling external programs
`snmptranslate` and `snmptable`, or "gosmi" which translates using the built-in
gosmi library.
- **statefile**: Name of the file to load the states of plugins from and store the states to.
If uncommented and not empty, this file is used to save the state of stateful
plugins on termination of Telegraf.
If the file exists on start, the state in the file is restored for the plugins.
- **always_include_local_tags**: Ensure tags explicitly defined in a plugin _always_ pass tag-filtering
via `taginclude` or `tagexclude`.
This removes the need to specify local tags twice.
- **always_include_global_tags**: Ensure tags explicitly defined in the `global_tags` section will _always_ pass
tag-filtering via `taginclude` or `tagexclude`.
This removes the need to specify those tags twice.
- **skip_processors_after_aggregators**: By default, processors are run a second time after aggregators.
Changing this setting to true will skip the second run of processors.
- **buffer_strategy**: The type of buffer to use for Telegraf output plugins.
Supported modes are `memory`, the default and original buffer type, and `disk`,
an experimental disk-backed buffer which serializes all metrics to disk as
needed to improve data durability and reduce the chance for data loss.
This is only supported at the agent level.
- **buffer_directory**: The directory to use when in `disk` buffer mode.
Each output plugin makes another subdirectory in this directory with the
output plugin's ID.
## Input configuration ## Input configuration
@ -371,40 +562,79 @@ Filters can be configured per input, output, processor, or aggregator.
### Filters ### Filters
Filters fall under two categories:
- [Selectors](#selectors)
- [Modifiers](#modifiers)
#### Selectors
Selector filters include or exclude entire metrics.
When a metric is excluded from an input or output plugin, the metric is dropped.
If a metric is excluded from a processor or aggregator plugin, it skips the
plugin and is sent onwards to the next stage of processing.
- **namepass**: An array of glob pattern strings. - **namepass**: An array of glob pattern strings.
Only emits points whose measurement name matches a pattern in this list. Only metrics whose measurement name matches a pattern in this list are emitted.
Additionally, custom list of separators can be specified using `namepass_separator`.
These separators are excluded from wildcard glob pattern matching.
- **namedrop**: The inverse of `namepass`. - **namedrop**: The inverse of `namepass`.
Discards points whose measurement name matches a pattern in this list. If a match is found the metric is discarded.
This test applies to points _after_ they have passed the `namepass` test. This is tested on metrics after they have passed the `namepass` test.
- **fieldpass**: An array of glob pattern strings. Additionally, custom list of separators can be specified using `namedrop_separator`.
Only emits fields whose field key matches a pattern in this list. These separators are excluded from wildcard glob pattern matching.
- **fielddrop**: The inverse of `fieldpass`. - **tagpass**: A table mapping tag keys to arrays of glob pattern strings.
Discards fields that have a field key matching one of the patterns. Only metrics that contain a tag key in the table and a tag value matching one of its
- **tagpass**: A table that maps tag keys to arrays of glob pattern strings. patterns is emitted.
Only emits points that contain a tag key in the table and a tag value that This can either use the explicit table syntax (for example: a subsection using a `[...]` header)
matches one of the associated patterns. or inline table syntax (e.g like a JSON table with `{...}`).
Please see the below notes on specifying the table.
- **tagdrop**: The inverse of `tagpass`. - **tagdrop**: The inverse of `tagpass`.
Discards points that contain a tag key in the table and a tag value that If a match is found the metric is discarded.
matches one of the associated patterns. This is tested on metrics after they have passed the `tagpass` test.
This test applies to points _after_ they have passed the `tagpass` test. - **metricpass**: A Common Expression Language (CEL) expression with boolean result where
`true` will allow the metric to pass, otherwise the metric is discarded.
This filter expression is more general compared to `namepass` and also
supports time-based filtering.
Further details, such as available functions and expressions, are provided in the
CEL language definition as well as in the extension documentation or the CEL language introduction.
> [!Note]
> *As CEL is an _interpreted_ language. This type of filtering is much slower
> than `namepass`, `namedrop`, and others.
> Consider using the more restrictive filter options where possible in case of
> high-throughput scenarios.
#### Modifiers
Modifier filters remove tags and fields from a metric.
If all fields are removed, the metric is removed and as a result not passed through
to the following processors or any output plugin.
Tags and fields are modified before a metric is passed to a processor,
aggregator, or output plugin.
When used with an input plugin the filter applies after the input runs.
- **fieldinclude**: An array of glob pattern strings.
Only fields whose field key matches a pattern in this list are emitted.
- **fieldexclude**: The inverse of `fieldinclude`.
Fields with a field key matching one of the patterns will be discarded from the metric.
This is tested on metrics after they have passed the `fieldinclude` test.
- **taginclude**: An array of glob pattern strings. - **taginclude**: An array of glob pattern strings.
Only tags with a tag key matching one of the patterns are emitted. Only tags with a tag key matching one of the patterns are emitted.
In contrast to `tagpass`, which emits an entire In contrast to `tagpass`, which will pass an entire metric based on its tag,
point if a tag passes, `taginclude` removes all non-matching tags from the `taginclude` removes all non matching tags from the metric.
point. This filter can be used on inputs and outputs, but is more efficient Any tag can be filtered including global tags and the agent `host` tag.
when used on inputs (filtering out tags is more efficient during ingestion). - **tagexclude**: The inverse of `taginclude`.
- **tagexclude**: Tags with a tag key matching one of the patterns will be discarded from the metric.
The inverse of `taginclude`. Tags with a tag key matching one of the patterns Any tag can be filtered including global tags and the agent `host` tag.
are discarded from the point.
{{% note %}} > [!Note]
#### Include tagpass and tagdrop at the end of your plugin definition > #### Include tagpass and tagdrop at the end of your plugin definition
>
Due to the way TOML is parsed, `tagpass` and `tagdrop` parameters > Due to the way TOML is parsed, `tagpass` and `tagdrop` parameters
must be defined at the _end_ of the plugin definition, otherwise subsequent > must be defined at the _end_ of the plugin definition, otherwise subsequent
plugin configuration options are interpreted as part of the tagpass and tagdrop > plugin configuration options are interpreted as part of the tagpass and tagdrop
tables. > tables.
{{% /note %}}
To learn more about metric filtering, watch the following video: To learn more about metric filtering, watch the following video:
@ -415,7 +645,9 @@ To learn more about metric filtering, watch the following video:
#### Input configuration examples #### Input configuration examples
The following example configuration collects per-cpu data, drops any The following example configuration collects per-cpu data, drops any
fields that begin with `time_`, tags measurements with `dc="denver-1"`, and then outputs measurements at a 10 s interval to an InfluxDB database named `telegraf` at the address `192.168.59.103:8086`. fields that begin with `time_`, tags measurements with `dc="denver-1"`, and then
outputs measurements at a 10 second interval to an InfluxDB database named
`telegraf` at the address `192.168.59.103:8086`.
```toml ```toml
[global_tags] [global_tags]
@ -491,6 +723,26 @@ interpreted as part of the tagpass and tagdrop tables.
namepass = ["rest_client_*"] namepass = ["rest_client_*"]
``` ```
#### Input Config: `namepass` and `namedrop` with separators
```toml
# Pass all metrics of type 'A.C.B' and drop all others like 'A.C.D.B'
[[inputs.socket_listener]]
data_format = "graphite"
templates = ["measurement*"]
namepass = ["A.*.B"]
namepass_separator = "."
# Drop all metrics of type 'A.C.B' and pass all others like 'A.C.D.B'
[[inputs.socket_listener]]
data_format = "graphite"
templates = ["measurement*"]
namedrop = ["A.*.B"]
namedrop_separator = "."
```
#### Input Config: `taginclude` and `tagexclude` #### Input Config: `taginclude` and `tagexclude`
```toml ```toml
@ -625,3 +877,55 @@ to the system load metrics due to the `namepass` parameter.
To learn more about configuring the Telegraf agent, watch the following video: To learn more about configuring the Telegraf agent, watch the following video:
{{< youtube txUcAxMDBlQ >}} {{< youtube txUcAxMDBlQ >}}
## Plugin selection via labels and selectors
You can control which plugin instances are enabled by adding labels to plugin
configurations and passing one or more selectors on the command line.
### Selectors
Provide selectors with one or more `--select` flags when starting Telegraf.
Each `--select` value is a semicolon-separated list of key=value pairs:
```text
<key>=<value>[;<key>=<value>]
```
- Pairs in a single `--select` value are combined with logical AND (all must match).
- Multiple `--select` flags are combined with logical OR (a plugin is enabled if it matches any selector set).
Selectors support simple glob patterns in values (for example `region=us-*`).
Example:
```console
telegraf --config config.conf --config-directory directory/ \
--select="app=payments;region=us-*" \
--select="env=prod" \
--watch-config --print-plugin-config-source=true
```
### Labels
Add an optional `labels` table to a plugin, similar to `tags`.
Keys and values are plain strings.
Example:
```toml
[[inputs.cpu]]
[inputs.cpu.labels]
app = "payments"
region = "us-east"
env = "prod"
```
Telegraf matches the command-line selectors against a plugin's labels to decide
whether that plugin instance should be enabled.
For details on supported syntax and matching rules, see the labels selectors spec.
## Transport Layer Security (TLS)
Many Telegraf plugins support TLS configuration for secure communication.
Reference the detailed TLS documentation for configuration options and examples.