Telegraf’s New Labels Feature Unlocks Smarter Plugin Control

By Scott Anderson / Developer, Product
Oct 22, 2025

Navigate to:

Telegraf 1.36 includes a powerful new feature that lets you add labels to plugins and enable or disable plugins dynamically at startup using labels. Telegraf labels and selectors offer new flexibility in how you configure and run your Telegraf agents—especially when you have many Telegraf instances sharing a set of configurations or want fine-grained control over which plugins run under specific conditions or in certain environments.

Let’s dive in.

What are Telegraf labels and selectors?

Labels and selectors let you attach metadata (labels) to plugin configurations and then choose which plugins are enabled using selectors (filter expressions).

This gives you a lot of expressive control over what Telegraf plugins to run. Want to run certain inputs only in staging environments? Label them env = "staging" and use a selector to enable them in staging and disable non-staging plugins. Want to temporarily disable a subset? Use selectors instead of entirely removing config blocks.

Add labels in your Telegraf configuration

To add labels to a plugin, include a labels subtable in your plugin configuration:

[[inputs.cpu]]
  percpu = true
  totalcpu = true

  [inputs.cpu.labels]
    env = "prod"
    region = "us-west"

[[inputs.mem]]
  [inputs.mem.labels]
    env = "prod"
    role = "monitoring"

[[outputs.influxdb_v2]]
  urls = ["http://localhost:8181"]
  token = "${INFLUX_TOKEN}"
  organization = ""
  bucket = "DATABASE_NAME"

  [outputs.influxdb_v2.labels]
    env = "prod"
    region = "us-west"

You can add labels to all plugin types (inputs, processors, aggregators, outputs).

Label Syntax & Examples

Each label is a key value pair associated with an equals sign (=). Keys and values support alphanumeric characters [A-Za-z0-9], dots (.), dashes (-), and underscores (_). The value must be formatted as a string literal.

env = "prod"
region = "us-west-1"

Use selectors to control plugin execution

Once labels are defined, use selectors to filter which plugins to run based on their labels. Use the --select flag when starting the Telegraf agent to apply one or more selectors. At startup, Telegraf parses the selector and eliminates any plugin instances that don’t match.

telegraf --select 'env=prod'

Selector Syntax & Examples

Selectors are predicate expressions that evaluate plugin labels and resolve to true or false. Telegraf selectors support the following operators:

  • Comparison Operators:
    • = : Equal to
  • Logical operators:
    • ;: (AND) Returns true if both operands are true, otherwise returns false
  • Wildcard operator:
    • * : Placeholder for unknown or variable characters

To combine predicate expressions using “and” logic, separate each predicate with a semi-colon (;) in a single selector. To combine predicate expressions using “or” logic, pass each predicate as a separate selector.

Some examples:

  • Run plugins with an env label that is prod:
telegraf --select 'env=prod'
  • Run plugins with an env label that is prod AND a region label that is us-west-1:
telegraf --select 'env=prod;region=us-west-1'
  • Run plugins with an env label that is prod OR a always_run label that is true:
telegraf \
  --select 'env=prod' \
  --select 'always_run=true'
  • Run plugins with a region label that begins with us-:
telegraf --select 'region=us-*'

How this helps in deployment scenarios

Here are some interesting use cases that benefit from labels and selectors:

  • Environment-based filtering: Maintain a single canonical telegraf.conf, label plugins for env = "dev" / "staging" / "prod", and choose which run per deployment.
  • Multi-tenant setups / multi-instance agents: If you run multiple Telegraf agents with overlapping configs, you can better isolate which plugin instances run per agent.
  • Gradual rollout / feature gating: Enable a new input or output only for certain subsets of agents via labels and selectors.
  • Switching degree of metric details: Defining a plugin instance twice, one instance with more detailed metrics and the other with less, each with corresponding labels. Use a selector to identify which plugin to run and control the level of metric details reported.

Because the filtering occurs before plugin initialization, you reduce resource usage (no unnecessary plugin startup) and simplify operations.

Try it yourself

  • Upgrade to the version of Telegraf 1.36+.
  • Add labels to plugin configurations.
  • Run Telegraf with --select to filter instances.
  • Provide feedback and report any edge cases that may surface.

We’d love to hear from you—try it out, tell us your use cases, and let us know how well this feature helps your deployments.