InfluxData Blog - Sven Rebhan

Telegraf Environment Variable Handling

Sven Rebhan (InfluxData) — Mon, 22 Dec 2025 08:00:00 +0000

In v1.38.0, Telegraf will switch to a stricter handling of environment variables by default. The new default ensures security; however, you will still be able to opt out to the current behavior in order to cover some rare use cases.

This blog post introduces you to environment variable handling in Telegraf and explains the new strict mode, why it is required, and when to opt out.

Environment variables in Telegraf

Environment variables can be used in Telegraf to reuse one set of configurations across different environments, to keep sensitive data out of configurations, and to easily adapt to dynamic environments such as containers where values are not known at the time the configuration is written.

The simplest example is to configure an InfluxDB output, such as:


[[outputs.influxdb_v2]]
  urls = ["http://${INFLUXDB_HOST}:${INFLUXDB_PORT:-8086}"]
  token = "${INFLUXDB_TOKEN}"
  organization = "${INFLUXDB_ORG_ID}"
  bucket = "${INFLUXDB_BUCKET}"

By setting environment variables before starting Telegraf, the user can fill in the host, port, token, organization, and bucket. The syntax for specifying the environment variables adheres to the compose specification, allowing to define behaviors for a variable, as in the example above, where: ${INFLUXDB_PORT:-8086} uses the default port of 8086 because the user did not specify INFLUXDB_PORT.

Non-strict handling of environment variables

Non-strict environment variable handling is the default until the release of v1.38.0. In this mode, Telegraf will perform text replacement of the environment variable before parsing the configuration. So, with the environment variables defined as:


INFLUXDB_HOST="localhost"
INFLUXDB_TOKEN="eyJhbGci…"
INFLUXDB_ORG_ID="myorg"
INFLUXDB_BUCKET="telegraf"

the example above will be interpolated to:


[[outputs.influxdb_v2]]
  urls = ["http://localhost:8086"]
  token = "eyJhbGci…"
  organization = "myorg"
  bucket = "telegraf"

In non-strict mode you can use environment variables wherever you want in the configuration as long as the resulting content after interpolation is valid TOML.

However, this freedom comes with the drawback of Telegraf not being able to impose any constraints on the content of the environment variables. As a result, a malicious user who has the ability to set environment variables in Telegraf could set the following:


INFLUXDB_HOST="localhost"
INFLUXDB_TOKEN="eyJhbGci…"
INFLUXDB_ORG_ID="myorg"
INFLUXDB_BUCKET=’telegraf"

[[inputs.exec]]
  commands = [echo "evil value=23i"]
  data_format="influx’

which will be interpolated to:


[[outputs.influxdb_v2]]
  urls = ["http://localhost:8086"]
  token = "eyJhbGci…"
  organization = "myorg"
  bucket = "telegraf"

[[inputs.exec]]
  commands = [echo "evil value=23i"]
  data_format="influx"

As you can see, this introduces a whole new plugin!

While this looks scary, it only poses a problem in cases where you can trust the Telegraf binary and configuration variables but not the execution environment.

Strict handling of environment variables

To improve the safety of handling environment variables, v1.36.4 introduced a strict mode that can be enabled using the --strict-env-handling command-line flag. Strict environment variable handling will be the default starting with v1.38.0.

In strict mode, the example above would be interpolated as


[[outputs.influxdb_v2]]
  urls = ["http://localhost:8086"]
  token = "eyJhbGci…"
  organization = "myorg"
  bucket = "telegraf\"\n\n[[inputs.exec]]\ncommands = [echo \"evil value=23i\"]\ndata_format=\"influx"

keeping the content of ${INFLUXDB_BUCKET} as a string not leaving the scope of bucket.

This is achieved by first parsing the configuration as TOML AST and then replacing only the content of nodes containing environment variables, ensuring that the content remains within the scope of the node. However, the drawback of this method is that the initial configuration must be valid TOML, so you cannot replace non-string variables with environment variables!

Call to action

With v1.38.0, the default environment variable handling will change to strict mode. Since v1.36.4, you can opt in to strict environment handling using the --strict-env-handling command-line flag. With v1.37.0, Telegraf also provides an opt out of strict environment variables using the --non-strict-env-handling command-line flag.

If you are not using environment variables, this change does not affect you, and you don’t need to do anything. If you are using environment variables only in string variables, you are also fine. To make sure your configuration is working in strict mode, you can run:

$ telegraf config check –strict-env-handling

If you see the error invalid TOML syntax, your config will likely not work in strict mode. In this case you can prepare by permanently adding the --non-strict-env-handling command-line flag when starting Telegraf. Only do so if you can trust the execution environment for Telegraf!

In case of any issues, please reach out via InfluxDB Community Slack or open an issue in our InfluxDB GitHub Repo.

Downloads

Head to our Downloads page to get the latest Telegraf release. If you find issues or have questions, please join our InfluxDB Community Slack, post them in our InfluxDB GitHub Repo or on our Community Site, and we will take a look.

InfluxDB University

Learn more about collecting data with Telegraf by taking the free InfluxDB University Data Collection with Telegraf course.

Call for Testing

Please fill out this form if you are interested in being included in testing bug fixes and features for the plugins and systems you are using. Telegraf maintainers will tag you on pull requests to test artifacts. This will help us better address bugs that may arise after a release.

Telegraf 1.37 Release Notes

Sven Rebhan (InfluxData) — Tue, 16 Dec 2025 08:00:00 +0000

A new feature-bearing release for Telegraf is now available:

Telegraf 1.37 — Release notes

You can find the binaries for the latest Telegraf release on our Downloads page. Many thanks to all the open source community members who contributed to this effort!

New plugins

These are the newest plugins, first available in this version:

Loki LogQL input (inputs.logql)
- Query data from Grafana Loki using LogQL
- Contributed by srebhan
NFTables input (inputs.nftables)
- Gather packets and byte counters for rules within Linux’s nftables
- Contributed by ansoni
Prometheus PromQL input (inputs.promql)
- Query metrics from Prometheus using PromQL
- Contributed by srebhan
Timex input (inputs.timex)
- Gather metrics on system time using the Linux Kernel adjtimex syscall
- Contributed by HappyTobi
ARC-DB output (outputs.arc)
- Write metrics to Arc, a high-performance time series database
- Contributed by xe-nvdk
Heartbeat output (outputs.heartbeat)
- Send a heartbeat signal via POST to a HTTP endpoint on a regular interval
- Contributed by srebhan
Google Cloud secret-store (secretstores.googlecloud)
- Retrieve token-based Google Cloud Credentials
- Contributed by iti-agrawal
HashiCorp Vault secret-store (secretstores.vault)
- Retrieve secrets stored in a HashiCorp Vault server
- Contributed by mstrandboge

Important changes

Here are some changes to highlight:

Handling of environment variables
- Telegraf v1.36.4 introduced a strict handling mode to prevent security issues. You can opt in using --strict-env-handling.
- This version adds an explicit opt out of the strict handling mode via --non-strict-env-handling. While the current default is still the non-strict handling mode, this flag was introduced in preparation for the next steps.
- In the next release (v1.38.0), we will change the default to strict handling of environment variables to be secure by default.
- Please check if your configuration works in strict environment variable handling mode! You can do this by running:
  
  telegraf config check –strict-env-handling

Check if TOML syntax errors appear. If so, please opt out of non-strict handling to ensure smooth future updates. * Support for IP filtering on socket_listener * Allows users to restrict remote senders to an IP whitelist. * Removal of deprecated options * We removed several deprecated options and option values in a number of plugins. * OPCUA self-signed certificates * Allows users to persist certificates auto-generated by the OPCUA plugins.

Downloads

Head to our Downloads page to get the latest Telegraf release. If you have issues or questions, please join our InfluxDB Community Slack or post them in our InfluxDB GitHub Repo or Community Site, and we will look into them.

InfluxDB University

Learn more about collecting data with Telegraf by taking the free InfluxDB University Data Collection with Telegraf course.

Telegraf 1.34 Release Notes

Sven Rebhan (InfluxData) — Wed, 12 Mar 2025 07:00:00 +0000

A new feature-bearing release for Telegraf is now available:

Telegraf 1.34 — Release notes

You can find the binaries for the latest Telegraf release on our Downloads page. Many thanks to all the open source community members who contributed to this effort!

New plugins

These are the newest plugins, first available in this version:

AWS Firehose service input (inputs.firehose)
- Listens for metrics sent by the AWS Data Firehose service
- Contributed by syedmhashim
Netgear Switch Discovery Protocol input (inputs.nsdp)
- Collects metrics from discovered Netgear devices
- Contributed by hdecarne
Hue bridge input (inputs.huebridge)
- Collects metrics from devices connected to Hue bridge devices, such as light or temperature sensors
- Contributed by hdecarne

Important changes

Here are some changes to highlight:

Support for input probing
- Framework that checks if all requirements for a plugin are fulfilled and ignores the plugin if they are not
- Implemented for the nvidia-smi input plugin
Kinesis consumer rework
- Removes outdated and unmaintained dependencies
- More robust persistence of shard iterators in DynamoDB
- Reduced number of reads in DynamoDB for expired iterators
Support for JKS and PKCS#12 keystores to x509_certs
- Allows evaluation of certificates in Java KeyStores
- Allows evaluation of certificates in PKCS#12 archives

Downloads

InfluxDB University

Learn more about collecting data with Telegraf by taking the free InfluxDB University Data Collection with Telegraf course.

Telegraf 1.33 Release Notes

Sven Rebhan (InfluxData) — Tue, 10 Dec 2024 07:00:00 +0000

A new feature-bearing release for Telegraf is now available:

Telegraf 1.33 — Release notes

You can find the binaries for the latest Telegraf release on our Downloads page. Many thanks to all the open source community members who contributed to this effort!

New plugins

These are the newest plugins, first available in this version:

Neoom Beaam input (inputs.neoom_beaam)
- Collect metrics from Neoom Beaam IoE gateway
  - Contributed by srebhan
Batch processor (processors.batch)
- Assign a batch tag to allow workload distribution
  - Contributed by LarsStegman
Quix output (outputs.quix)
- Send metrics to Quix processing pipelines
  - Contributed by tomas-quix

Important changes

Here are some changes to highlight:

Rate-limiting framework and implementation for InfluxDBv2 output
- Allows controlling data rate for sending data
- Allows avoiding transmission bursts
- Implementation of fixed-window rate-limiter for outputs
- Implementation for InfluxDBv2 output
- For now, this only works on uncompressed data
Performance improvements
- Avoids copying filtered metrics for outputs
- Ability to process data in parallel for socket-listener input
Option to select timestamp source for inputs
- Allows choice of metric timestamp from different sources:
  - Beginning of the collection interval
  - End of the collection interval
  - Keep the time set in the metric (default)
- Potential to ease merge of metrics collected in the same interval
- Not available for service inputs
Removal of deprecated API for instantiating serializers
- Use direct instantiation instead
- Only potentially affects developers of external and out-of-tree plugins

Downloads

Head to our Downloads page to get the latest Telegraf release. If you have issues or questions, please join our InfluxDB Community Slack, post them in our InfluxDB GitHub Repo, or our Community Site, and we will take a look.

InfluxDB University

Learn more about collecting data with Telegraf by taking the free InfluxDB University Data Collection with Telegraf course.

Telegraf 1.32 Release Notes

Sven Rebhan (InfluxData) — Fri, 13 Sep 2024 08:00:00 +0000

A new feature-bearing release for Telegraf is now available:

Telegraf 1.32 — Release notes

You can find the binaries for the latest Telegraf release on our Downloads page. Many thanks to all the open source community members who contributed to this effort!

New plugins

These are the newest plugins, first available in this version:

SLURM workload manager input (`inputs.slurm`)
- Collect job, node, and other metadata information from SLURM cluster
- Contributed by pcolladosoto
Parquet file writer output (`outputs.parquet`)
- Write metrics to parquet files
- Contributed by powersj
Remote file output (`outputs.remotefile`)
- Send metrics to files in remote locations like Amazon S3
- Contributed by srebhan

Important changes

Here are some changes to highlight:

Logging framework overhaul
- Cleanup and rework the underlying logging code
- Per-plugin log-level settings via log_level setting
- New trace log-level for low-level debugging of plugins
- Introduction of structured logging; consequently, the logtarget setting is deprecated and replaced by logformat. For using eventlog please set the logformat accordingly!
- Log-level selection for external programs executed via inputs.execd by providing log-level prefixes
Disk-backed metric buffer for outputs
- Avoid metric-buffer overflow by using a write-ahead-log
- Enable for all plugins via buffer_strategy agent setting
- Experimental feature
Agent enhancements
- Verify configuration files using the telegraf config check command
- Watch for new and deleted configuration files

Downloads

InfluxDB University

Learn more about collecting data with Telegraf by taking the free InfluxDB University Data Collection with Telegraf course.

Telegraf Configuration Migration

Sven Rebhan (InfluxData) — Mon, 04 Mar 2024 08:00:00 +0000

In v1.30.0, Telegraf will remove a few long-standing deprecated plugins. These plugins have been deprecated for a number of years, and plugins with better support and configuration options now replace them. This version of Telegraf also removes a number of configuration options.

The full list of deprecated plugins includes:

inputs.cassandra
inputs.httpjson
inputs.io
inputs.jolokia
inputs.kafka_consumer_legacy
inputs.snmp_legacy
inputs.tcp_listener
inputs.udp_listener
outputs.riemann_legacy

Starting from v1.30.0 Telegraf will show an error message and stop running if any of the plugins or options are present in your configuration.

Migrating configurations

To assist users with adapting their configuration(s), Telegraf comes with a migration tool to help you replace deprecated plugins and options with new, maintained equivalents where possible.

To migrate your existing configuration in /etc/telegraf/telegraf.confand /etc/telegraf/telegraf.d` you can run

$ sudo telegraf config migrate

In case your configuration differs or you only want to migrate a specific file, use the --config and --config-directory options, e.g.:

$ telegraf  –config mytelegraf.conf –config-directory ~/telegraf.d config migrate

The command will load each configuration file, apply available migrations if needed and, in case any migration was applied, save the migrated configuration to a file with the .migrated file suffix in the same location.

Important notes

Please read the output of the migration command carefully! Some plugins cannot be converted automatically, or there is no drop-in replacement available. Those cases require a manual migration of the configuration. Furthermore, metric properties such as name, tag keys, or field key might change. The migration command will notify you ‌in those cases.
Please check the migrated configuration! The original configuration file _remains in place and unchanged_ by default. If the changes from the migration tool are OK, you should replace the config file manually.
The migration tool removes comments for migrated plugins and keeps comments for any untouched, unaffected plugins.

Downloads

InfluxDB University

Learn more about collecting data with Telegraf by taking the free InfluxDB University Data Collection with Telegraf course.

InfluxData Blog - Sven Rebhan

Telegraf Environment Variable Handling

Environment variables in Telegraf

Non-strict handling of environment variables

Strict handling of environment variables

Call to action

Downloads

InfluxDB University

Call for Testing

Telegraf 1.37 Release Notes

New plugins

Important changes

Downloads

InfluxDB University

Telegraf 1.34 Release Notes

New plugins

Important changes

Downloads

InfluxDB University

Telegraf 1.33 Release Notes

New plugins

Important changes

Downloads

InfluxDB University

Telegraf 1.32 Release Notes

New plugins

Important changes

Downloads

InfluxDB University

Telegraf Configuration Migration

Migrating configurations

Important notes

Downloads

InfluxDB University

Call for testing