From 07bfb6f8cd9c56520562ca1d7400b6df19a4b0cf Mon Sep 17 00:00:00 2001 From: Sergii Kauk <471067+skauk@users.noreply.github.com> Date: Fri, 7 Nov 2025 23:14:55 +0100 Subject: [PATCH 1/4] fix: library descriptions and links (#6518) Corrected description of available libraries --- .../v1/processor-plugins/starlark/_index.md | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/content/telegraf/v1/processor-plugins/starlark/_index.md b/content/telegraf/v1/processor-plugins/starlark/_index.md index a21e46083..7b8f8501c 100644 --- a/content/telegraf/v1/processor-plugins/starlark/_index.md +++ b/content/telegraf/v1/processor-plugins/starlark/_index.md @@ -141,17 +141,19 @@ following libraries are available for loading: - json: `load("json.star", "json")` provides the functions `json.encode()`, `json.decode()`, `json.indent()`. See json.star for an example. For more details about the functions, please refer to the - [library documentation](https://pkg.go.dev/go.starlark.net/lib/time). + [library documentation](https://pkg.go.dev/go.starlark.net/lib/json). - log: `load("logging.star", "log")` provides the functions `log.debug()`, - `log.info()`, `log.warn()`, `log.error()`. See - logging.star` provides the function - [documented in the library](https://pkg.go.dev/go.starlark.net/lib/math). See - math.star`. See - time_date.star, - time_duration.star and - time_timestamp.star for examples. For - more details about the functions, please refer to the - [library documentation](https://pkg.go.dev/go.starlark.net/lib/time). + `log.info()`, `log.warn()`, `log.error()`. See logging.star` for an example. +- math: `load('math.star', 'math')` provides basic mathematical constants and functions. + See math.star for an example. For more details, please refer to the + [library documentation](https://pkg.go.dev/go.starlark.net/lib/math). +- time: `load('time.star', 'time')` provides time-related constants and functions. + See + time_date.star, + time_duration.star and + time_timestamp.star for examples. For + more details about the functions, please refer to the + [library documentation](https://pkg.go.dev/go.starlark.net/lib/time). If you would like to see support for something else here, please open an issue. From 08bc79ff3eb19dfa4a90e5ef117d3987aa99d369 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Fri, 7 Nov 2025 15:50:09 -0700 Subject: [PATCH 2/4] 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 --------- Co-authored-by: Jason Stirnaman --- .husky/_/pre-commit | 16 +- .husky/_/pre-push | 16 +- .husky/_/prepare-commit-msg | 16 +- content/telegraf/v1/configuration.md | 548 +++++++++++++++++++++------ 4 files changed, 432 insertions(+), 164 deletions(-) diff --git a/.husky/_/pre-commit b/.husky/_/pre-commit index 710b28856..4855f6124 100755 --- a/.husky/_/pre-commit +++ b/.husky/_/pre-commit @@ -33,9 +33,6 @@ call_lefthook() then "$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 then bundle exec lefthook "$@" @@ -45,21 +42,12 @@ call_lefthook() elif pnpm lefthook -h >/dev/null 2>&1 then pnpm lefthook "$@" - elif swift package lefthook >/dev/null 2>&1 + elif swift package plugin lefthook >/dev/null 2>&1 then - swift package --build-path .build/lefthook --disable-sandbox lefthook "$@" + swift package --disable-sandbox plugin lefthook "$@" elif command -v mint >/dev/null 2>&1 then 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 echo "Can't find lefthook in PATH" fi diff --git a/.husky/_/pre-push b/.husky/_/pre-push index 17b532e00..a0d96ef93 100755 --- a/.husky/_/pre-push +++ b/.husky/_/pre-push @@ -33,9 +33,6 @@ call_lefthook() then "$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 then bundle exec lefthook "$@" @@ -45,21 +42,12 @@ call_lefthook() elif pnpm lefthook -h >/dev/null 2>&1 then pnpm lefthook "$@" - elif swift package lefthook >/dev/null 2>&1 + elif swift package plugin lefthook >/dev/null 2>&1 then - swift package --build-path .build/lefthook --disable-sandbox lefthook "$@" + swift package --disable-sandbox plugin lefthook "$@" elif command -v mint >/dev/null 2>&1 then 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 echo "Can't find lefthook in PATH" fi diff --git a/.husky/_/prepare-commit-msg b/.husky/_/prepare-commit-msg index 6efab23a3..2655902bc 100755 --- a/.husky/_/prepare-commit-msg +++ b/.husky/_/prepare-commit-msg @@ -33,9 +33,6 @@ call_lefthook() then "$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 then bundle exec lefthook "$@" @@ -45,21 +42,12 @@ call_lefthook() elif pnpm lefthook -h >/dev/null 2>&1 then pnpm lefthook "$@" - elif swift package lefthook >/dev/null 2>&1 + elif swift package plugin lefthook >/dev/null 2>&1 then - swift package --build-path .build/lefthook --disable-sandbox lefthook "$@" + swift package --disable-sandbox plugin lefthook "$@" elif command -v mint >/dev/null 2>&1 then 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 echo "Can't find lefthook in PATH" fi diff --git a/content/telegraf/v1/configuration.md b/content/telegraf/v1/configuration.md index e338f3d8e..d3016c30c 100644 --- a/content/telegraf/v1/configuration.md +++ b/content/telegraf/v1/configuration.md @@ -16,9 +16,8 @@ settings to use when Telegraf starts. Each Telegraf plugin has its own set of configuration options. Telegraf also provides global options for configuring specific Telegraf settings. -{{% note %}} -See [Get started](/telegraf/v1/get_started/) to quickly get up and running with Telegraf. -{{% /note %}} +> [!Note] +> See [Get started](/telegraf/v1/get_started/) to quickly get up and running with Telegraf. ## 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 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 @@ -118,6 +118,23 @@ config > telegraf.conf For more advanced configuration details, see the [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 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. If any file isn't a valid configuration, Telegraf returns an error. -{{% warn %}} - -#### Telegraf doesn't support partial configurations - -Telegraf doesn't concatenate configuration files before processing them. -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 -own custom code to concatenate and pre-process the files, and then provide the -complete configuration to Telegraf--for example: - -1. Configure plugin sections and assign partial configs a file extension different - from `.conf` to prevent Telegraf loading them--for example: - - ```toml - # main.opcua: Main configuration file - ... - [[inputs.opcua_listener]] - name = "PluginSection" - endpoint = "opc.tcp://10.0.0.53:4840" - ... - ``` - - ```toml - # group_1.opcua - [[inputs.opcua_listener.group]] - name = "SubSection1" - ... - ``` - - ```toml - # group_2.opcua - [[inputs.opcua_listener.group]] - name = "SubSection2" - ... - ``` - -2. Before you start Telegraf, run your custom script to concatenate `main.opcua`, `group_1.opcua`, - `group_2.opcua` into a valid `telegraf.conf`. -3. Start Telegraf with the complete, valid `telegraf.conf` configuration. - -{{% /warn %}} +> [!Warning] +> #### Telegraf doesn't support partial configurations +> +> Telegraf doesn't concatenate configuration files before processing them. +> 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 +> own custom code to concatenate and pre-process the files, and then provide the +> complete configuration to Telegraf--for example: +> +> 1. Configure plugin sections and assign partial configs a file extension different +> from `.conf` to prevent Telegraf loading them--for example: +> +> ```toml +> # main.opcua: Main configuration file +> ... +> [[inputs.opcua_listener]] +> name = "PluginSection" +> endpoint = "opc.tcp://10.0.0.53:4840" +> ... +> ``` +> +> ```toml +> # group_1.opcua +> [[inputs.opcua_listener.group]] +> name = "SubSection1" +> ... +> ``` +> +> ```toml +> # group_2.opcua +> [[inputs.opcua_listener.group]] +> name = "SubSection2" +> ... +> ``` +> +> 2. Before you start Telegraf, run your custom script to concatenate + `main.opcua`, `group_1.opcua`, +> `group_2.opcua` into a valid `telegraf.conf`. +> 3. Start Telegraf with the complete, valid `telegraf.conf` configuration. ## Set environment variables 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 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: + + +```bash +export password=mypassword +``` > **Note:** Use a secret store or environment variables to store sensitive credentials. ### 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: @@ -199,7 +245,31 @@ Set environment variables in the Telegraf environment variables file (`/etc/defa USER="alice" INFLUX_URL="http://localhost:8086" INFLUX_SKIP_DATABASE_CREATION="true" -INFLUX_PASSWORD="monkey123" +INFLUX_PASSWORD="passw0rd123" +``` + +#### For InfluxDB OSS v2: + + + +```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: + + + +```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: @@ -210,10 +280,25 @@ In the Telegraf configuration file (`/etc/telegraf.conf`), reference the variabl [[inputs.mem]] +# For InfluxDB 1.x: [[outputs.influxdb]] urls = ["${INFLUX_URL}"] skip_database_creation = ${INFLUX_SKIP_DATABASE_CREATION} 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: @@ -222,68 +307,174 @@ When Telegraf runs, the effective configuration is the following: [global_tags] user = "alice" +# For InfluxDB 1.x: [[outputs.influxdb]] - urls = "http://localhost:8086" + urls = ["http://localhost:8086"] 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`: 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 can be specified in the `[global_tags]` section of the configuration file -in `key="value"` format. +Global tags can be specified in the `[global_tags]` section of the configuration +file in `key="value"` format. Telegraf applies the global tags to all metrics gathered on this host. ## Agent configuration 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`. 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. -- **metric_buffer_limit**: Caches `metric_buffer_limit` metrics - for each output, and flushes this buffer on a successful write. - This should be a multiple of `metric_batch_size` and could not be less - than 2 times `metric_batch_size`. -- **collection_jitter**: Used to jitter the collection by a random amount. - Each plugin sleeps for a random time within jitter before collecting. - This can be used to avoid many plugins querying things like **sysfs** at the + This controls the size of writes that Telegraf sends to output plugins. +- **metric_buffer_limit**: Maximum number of unwritten metrics per output. + Increasing this value allows for longer periods of output downtime without + dropping metrics at the cost of higher maximum memory usage. + The oldest metrics are overwritten in favor of new ones when the buffer fills up. +- **collection_jitter**: Jitter the collection by a random interval. + 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. -- **flush_interval**: Default data flushing interval for all outputs. - Don't set this below `interval`. - Maximum `flush_interval` is `flush_interval` + `flush_jitter` -- **flush_jitter**: Jitter the flush interval by a random amount. - This is primarily to avoid - large write spikes for users running a large number of Telegraf instances. - For example, a `flush_jitter` of `5s` and `flush_interval` of `10s` means - flushes happen every 10-15s. -- **precision**: Collected metrics are rounded to the precision specified as an - `interval` (integer + unit, ex: `1ns`, `1us`, `1ms`, and `1s` . Precision isn't - used for service inputs, such as `logparser` and `statsd`. -- **debug**: Run Telegraf in debug mode. -- **quiet**: Run Telegraf in quiet mode (error messages only). -- **logtarget**: Controls the destination for logs and can be set to `"file"`, - `"stderr"`, or, on Windows, `"eventlog"`. - When set to `"file"`, the output file is determined by the logfile setting. -- **logfile**: If logtarget is set to `“file”`, specify the logfile name. - If set to an empty string, then logs are written to stderr. -- **logfile_rotation_interval**: Rotates the logfile after the time interval specified. - When set to `0`, no time-based rotation is performed. -- **logfile_rotation_max_size**: Rotates logfile when it becomes larger than the - specified size. - When set to `0`, no size-based rotation is performed. +- **collection_offset**: Shift the collection by the given interval. + Use this to avoid many plugins querying constraint devices + at the same time by manually scheduling them in time. +- **flush_interval**: Default flushing interval for all outputs. + Maximum `flush_interval` is `flush_interval` + `flush_jitter`. +- **flush_jitter**: Default flush jitter for all outputs. + This jitters the flush interval by a random amount. + This is primarily to avoid large write spikes for users + running a large number of Telegraf instances. + For example, a jitter of `5s` and an interval of `10s` means flushes happen + every 10-15 seconds. +- **precision**: Round collected metrics to the precision specified as an interval. + Precision is _not_ used for service inputs. + It is up to each individual service input to set the timestamp at the appropriate precision. +- **debug**: Log at debug level. +- **quiet**: Log only error level messages. +- **logformat**: Log format controls the way messages are logged and can be one + of `text`, `structured` or, on Windows, `eventlog`. + The output file (if any) is determined by the `logfile` setting. +- **structured_log_message_key**: Message key for structured logs, to override + the default of `msg`. + Ignored if `logformat` is not `structured`. +- **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, any older logs are deleted. - If set to `-1`, no archives are removed. -- **log_with_timezone**: Set a timezone to use when logging--for example, `"America/Chicago"`. - To use local time, set to `"local"`. - See [timezone options and formats](https://socketloop.com/tutorials/golang-display-list-of-timezones-with-gmt). -- **hostname**: Override default hostname, if empty use `os.Hostname()`. -- **omit_hostname**: If true, do not set the `host` tag in the Telegraf agent. -- **skip_processors_after_aggregators**: If true, processors do not run again - after aggregators. Default is false. + If set to -1, no archives are removed. +- **log_with_timezone**: Pick a timezone to use when logging or type 'local' for local time. + Example: 'America/Chicago'. + [See this page for options/formats.](https://socketloop.com/tutorials/golang-display-list-of-timezones-with-gmt) +- **hostname**: Override the default hostname, if empty use `os.Hostname()`. +- **omit_hostname**: If set to true, do no set the "host" tag in the Telegraf agent. +- **snmp_translator**: Method of translating SNMP objects. + 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 @@ -371,40 +562,79 @@ Filters can be configured per input, output, processor, or aggregator. ### 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. - 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`. - Discards points whose measurement name matches a pattern in this list. - This test applies to points _after_ they have passed the `namepass` test. -- **fieldpass**: An array of glob pattern strings. - Only emits fields whose field key matches a pattern in this list. -- **fielddrop**: The inverse of `fieldpass`. - Discards fields that have a field key matching one of the patterns. -- **tagpass**: A table that maps tag keys to arrays of glob pattern strings. - Only emits points that contain a tag key in the table and a tag value that - matches one of the associated patterns. + If a match is found the metric is discarded. + This is tested on metrics after they have passed the `namepass` test. + Additionally, custom list of separators can be specified using `namedrop_separator`. + These separators are excluded from wildcard glob pattern matching. +- **tagpass**: A table mapping tag keys to arrays of glob pattern strings. + Only metrics that contain a tag key in the table and a tag value matching one of its + patterns is emitted. + This can either use the explicit table syntax (for example: a subsection using a `[...]` header) + 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`. - Discards points that contain a tag key in the table and a tag value that - matches one of the associated patterns. - This test applies to points _after_ they have passed the `tagpass` test. + If a match is found the metric is discarded. + This is tested on metrics 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. Only tags with a tag key matching one of the patterns are emitted. - In contrast to `tagpass`, which emits an entire - point if a tag passes, `taginclude` removes all non-matching tags from the - point. This filter can be used on inputs and outputs, but is more efficient - when used on inputs (filtering out tags is more efficient during ingestion). -- **tagexclude**: - The inverse of `taginclude`. Tags with a tag key matching one of the patterns - are discarded from the point. + In contrast to `tagpass`, which will pass an entire metric based on its tag, + `taginclude` removes all non matching tags from the metric. + Any tag can be filtered including global tags and the agent `host` tag. +- **tagexclude**: The inverse of `taginclude`. + Tags with a tag key matching one of the patterns will be discarded from the metric. + Any tag can be filtered including global tags and the agent `host` tag. -{{% note %}} -#### Include tagpass and tagdrop at the end of your plugin definition - -Due to the way TOML is parsed, `tagpass` and `tagdrop` parameters -must be defined at the _end_ of the plugin definition, otherwise subsequent -plugin configuration options are interpreted as part of the tagpass and tagdrop -tables. -{{% /note %}} +> [!Note] +> #### Include tagpass and tagdrop at the end of your plugin definition +> +> Due to the way TOML is parsed, `tagpass` and `tagdrop` parameters +> must be defined at the _end_ of the plugin definition, otherwise subsequent +> plugin configuration options are interpreted as part of the tagpass and tagdrop +> tables. 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 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 [global_tags] @@ -491,6 +723,26 @@ interpreted as part of the tagpass and tagdrop tables. 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` ```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: {{< 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 +=[;=] +``` + +- 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. From 79e5e20506967943491f854bc57aec3d7409074b Mon Sep 17 00:00:00 2001 From: joe miller Date: Mon, 10 Nov 2025 08:33:59 -0800 Subject: [PATCH 3/4] fix: spelling of turbostat (#6519) --- content/telegraf/v1/input-plugins/turbostat/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/telegraf/v1/input-plugins/turbostat/_index.md b/content/telegraf/v1/input-plugins/turbostat/_index.md index 9b4a08029..6876233d2 100644 --- a/content/telegraf/v1/input-plugins/turbostat/_index.md +++ b/content/telegraf/v1/input-plugins/turbostat/_index.md @@ -83,7 +83,7 @@ times, or with a comma-separated list of column names. times, or with a comma-separated list of column names. Be careful not to hide CPU, Core, Package, and Die, or the output may lose much of its meaning. -To discover the list of available columns, run `sudo tubostat --list`. +To discover the list of available columns, run `sudo turbostat --list`. For further information, run `man turbostat`. If the man page is not installed, download [turbostat.8](https://raw.githubusercontent.com/torvalds/linux/refs/heads/master/tools/power/x86/turbostat/turbostat.8) and browse it with `man ./turbostat.8`. From 1a7bb448b2271afeca25e4d7aea02cffc8856429 Mon Sep 17 00:00:00 2001 From: rcater Date: Mon, 10 Nov 2025 08:10:02 -0600 Subject: [PATCH 4/4] chore(powerbi): update powerbi pqx to latest version --- static/downloads/InfluxDB.pqx | Bin 32616 -> 32610 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/static/downloads/InfluxDB.pqx b/static/downloads/InfluxDB.pqx index 3e102cc017873a69c1f561a5c1bde8a02fe07fcf..089566fc8ae023db4a5777f7be19eb78d1a7d94f 100644 GIT binary patch delta 3400 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 delta 3459 zcmai136v9Mwod3qHbI)kK1$2hGk|vJt|gUJibbrX(n)2l>`Om^q_!lLt+FRH9Tjy1 zeWOemK*0@YbskHLjWQ|-t<1P^pyiFjIPe4p1_41wWE?@;c9NEP>O1e8`Rm;C-+TZ2 z-}|rk|LXLR^!$)?JY}q_pDd9`MoZu@v~&EmQRAz1XZNeW#9AjwBzN~Uj@~$-{A6%@ zU(>2B?8DP8-3tM0k4m4IsB6=lcw#ZFKYY!)TfFUt)U4LlPuAV_;th^%=YYDe)!&Y9 zIzMOCrugJczwEcGs3nJ6e~DhYGBh-MPtTE;JxiAL-Ofy0e3bu7X;FjW{PTTHE5(bW zM^BtKX7asb?&`UJ5FU#nzp_2%Z*QMXE3@U_f4qj+{oUNZpYz?ae)k6Eu`C8hu9mL$ zzn_BlwqAH-{vdU-{@}(yqkUC2^ZDFuXU;9%JAab*!VG%g#MFhy`sxSlpDcbbH@I!b z)NrQ^gKa~AyeRLjqO=x1BE zynAEk-z(2pKFq&qZB=S8Q*_Xxt z3N?35psyZnnm*thKktP4n!;$AZL^yPUSRf8--MbzZ8rYLQgF+9Pxw5Y&5~Y?Wp*AGv>5R(vt3vu$5y$M&g!u&bx5Z^KM>DX?WIY8m&@-?n5% zl7A`;4b(5id+(lE^nP=43U#z)+netmXqvJ**nHn9?RVX4PJ9k@Zr@gJJoPFKz&FkL zon~L%-zxtdZ2yu>{AS~q&mHRByz+}>$D%jtMxNVsbuxcjuBE;8@WbwP>?^-s(+iX@ z#KxTcWW47ubQ}Mhi+w}S96zr(u3a~< zn7VkZe(+>w$LjayZ2e-D^?%Bbi2Z+B(%b*;S9>qM^T1v6u3c$(vHO$$=nsuOF9GWg>gU>HgOru?@WW z`qq`<@Bhno%SZ~SOPZ?EL$1((lxe7}0QI5=|if@QJ;;*$-w z_RE*gjyv`_o$5I>IF~x!KrEhnuyH?kc<3Ks!^}+x{=JO@+cJGv^R;*PsJc+q;jX0% zq&22;CBToa)}1FOymEhEFxV-b2nLiKr-HDc9OMvC4p$D*(;8|f8Oer~d8tHFqxltS zaCT)!_bq+%7+iWMq(V`c2|%b4rV#}OVKk=<1_BJmVH}8YXnQivqzmbm86>l?#g0KJ z2qQrRW{_$GC0dIxJcw6$R9QL6E}Zf2{Piv1zLGXaL}k>VqC-jm$hZ+ajOG$3?6p&d z5?#3`ds`(Ex~LkclQ#S!Y9P5~o^ zqQ#BsgITjXrB0>PF=duFTSOp0kyb$<-3r0zbjFo=vnedoC)|{Z<1H{J`ncC0>?zaWeCL{rA#v{5Rdvn zl?@Nz_Bp@*nKNcim z8;dc3g@6g3#IqQha5}wC9$-`nHB_J>Q!1TDd<;=6xp}}Wcyv+3VbYa#dOxKvX#L8R z(XR|a2{P^!w3s;W1oN}0TIKe#PMo5FwieL(b$&TwC!7vhwWk{g|2Qw@kB&z*QHXnqC3G^ zRERr=8|i{lOBneqq0q<}zlt}+<IllA$A%WVPW!ITV7O1(jXLip3b4U;-Kgs8CZ*9l~R%!RIDQd4Y7r z7Ik?&jLqR8OsmXiW1P`jFa+cv zKxVCo-09NmN)AWVXfc5XG3Az_wkQ|!$9dT3h{*kJlMci!X`xWarz~MP307{6C&~oi zF@wQE)*O!HDIM>{Fkjg2;?aWMjDtE&^;9^>pq#L2)tbBu#}QJE+Xx~9DKo4C4giFf z^Cci%L`h``G8-lgFktNPDq@7zz{Fi?KnBab1$i!&MPQu`eiD{i9f+SGEqbM@GO|SBxoRta{%|2xk zPKU}F*qHQkm^tCE<`=alp)+GiR373~DRl$~oM6Ey`i<4p98P#iV@Ez`$qRs4t6}4A zd(e)h^LBUAX9Xhph+CHQ(&iE<)3O=2-v|^zwJ{+wj)bu!hYL;}joBhttb?_CY_tuc zMVVP1mB+{H69pY;#ZXdZGurzmB{xZ@h&iX6N%duXu1XWCNd1S>SXsSn>aeGs%bKOHRSsR3KCMd6 zR>pLF-*!h=^TOw5{SXBK|Gy|#7Ek}<`5PpXGgbO&l$DixuX}p7t6BPLW$$(AqpCEz za_zcw>+)u)siIguqqFw^FvFFRq((_3?KA$bw<}(WB*mr^*%ZyD+pApR$MdbBftSFa zWxl9R^63#0N#hTbt#aEdFD`GHUbFeJ8vL;!xm3Ble9^E?4S1NUYgVIiKe2IFtld+F zaX}4vRK)J4x^uLoGDI(^p8MM3j~zCz1*!oDS9LFHR2}(`${#A1yOD+e4o_UiCzNqy TbzLQrhU&MzULtv|RFnP*IqulY