# How Telegraf Plugin Labels and Selectors Enable Selective Plugin Loading

> Telegraf plugin labels and selectors enable selective plugin loading by filtering plugins with metadata and Kubernetes-style expressions. Use one config for multiple environments.

- Repository: [InfluxData/telegraf](https://github.com/influxdata/telegraf)
- Tags: internals
- Published: 2026-05-14

---

**Telegraf plugin labels and selectors allow operators to filter which plugins run at startup by attaching metadata key-value pairs to plugin instances and applying Kubernetes-style selector expressions, enabling a single configuration file to serve multiple environments without code changes.**

Telegraf, the open-source server agent from InfluxData, supports selective plugin loading through a powerful labeling system. By combining **Telegraf plugin labels and selectors**, you can deploy one configuration file across development, staging, and production environments while controlling exactly which plugins instantiate at runtime. This capability centers on metadata labels defined in TOML configuration blocks and filter expressions processed during agent startup.

## How Plugin Labels Attach Metadata to Plugins

Plugin labels are arbitrary key-value pairs defined in the TOML configuration that provide metadata for individual plugin instances. These labels serve as the targeting mechanism for selective loading.

### Defining Labels in TOML Configuration

In any plugin's configuration block, you can declare a `labels` table to attach metadata:

```toml
[[inputs.cpu]]
  interval = "10s"
  [inputs.cpu.labels]
    env = "prod"
    role = "monitor"
    tier = "frontend"

```

The parser stores these labels as a `map[string]string` on the plugin's internal `Config` struct, making them available for evaluation during the filtering phase.

## Understanding Plugin Selectors for Filtered Loading

Plugin selectors are filter expressions that follow Kubernetes label and field selector syntax. They determine which labeled plugins to include or exclude during agent initialization.

### Selector Expression Syntax

Selectors support exact matches, negations, set-based operations, and field selection:

- `env=prod` – Match plugins where label `env` equals `prod`
- `role in (db, web)` – Match where `role` is either `db` or `web`
- `deprecated!=true` – Exclude plugins with label `deprecated=true`
- `type=output` – Field selector matching plugin type

### Configuring Selectors in Telegraf

Selectors can be defined in the configuration file within a `[plugin_selector]` section or passed via command-line flags.

In [`telegraf.conf`](https://github.com/influxdata/telegraf/blob/main/telegraf.conf):

```toml
[plugin_selector]
  selector_include = ["env=prod", "role!=test"]
  selector_exclude = ["deprecated=true"]

```

Via CLI:

```bash
telegraf --plugin-selector "env=prod"

```

## The Runtime Filtering Mechanism

The selective loading process occurs during agent startup in [`agent/agent.go`](https://github.com/influxdata/telegraf/blob/main/agent/agent.go), where the `filterPlugins` function applies parsed selectors against plugin label sets.

### Parsing Selectors

The [`config/plugin_selector.go`](https://github.com/influxdata/telegraf/blob/main/config/plugin_selector.go) file handles selector string parsing, utilizing `labels.Parse` and `fields.ParseSelector` from the `k8s.io/apimachinery` package to create `labels.Selector` and `fields.Selector` objects:

```go
// Concepts from config/plugin_selector.go
selectorInclude, _ := labels.Parse("env=prod")
selectorExclude, _ := labels.Parse("deprecated=true")

```

### The filterPlugins Implementation

During agent initialization in [`agent/agent.go`](https://github.com/influxdata/telegraf/blob/main/agent/agent.go), the `filterPlugins` routine evaluates each plugin:

```go
for _, p := range plugins {
    if selectorInclude.Matches(p.Labels) && !selectorExclude.Matches(p.Labels) {
        // Keep and instantiate this plugin
    } else {
        // Remove from plugin list - Gather/Write never called
    }
}

```

Plugins that fail include selectors or match exclude selectors are discarded before instantiation, reducing memory footprint and CPU usage.

## Practical Examples of Selective Plugin Loading

### Single Environment Deployment

Run only production plugins:

```bash
telegraf --plugin-selector "env=prod"

```

Or in configuration:

```toml
[plugin_selector]
  selector_include = ["env=prod"]

```

### Excluding Deprecated Plugins

Prevent loading of deprecated plugin instances:

```toml
[plugin_selector]
  selector_exclude = ["deprecated=true"]

```

### Complex Include and Exclude Logic

Combine selectors for precise control:

```toml
[plugin_selector]
  selector_include = ["role=monitor", "tier=frontend"]
  selector_exclude = ["env=dev", "region=archive"]

```

This configuration loads only frontend monitoring plugins that are not in the development environment or archive region.

## Summary

- **Telegraf plugin labels** attach metadata to plugin instances via TOML configuration tables, enabling classification by environment, role, or custom attributes.
- **Plugin selectors** use Kubernetes-compatible expression syntax to filter plugins during startup, supporting both inclusion and exclusion patterns.
- The `filterPlugins` function in [`agent/agent.go`](https://github.com/influxdata/telegraf/blob/main/agent/agent.go) evaluates selectors against label sets after parsing via [`config/plugin_selector.go`](https://github.com/influxdata/telegraf/blob/main/config/plugin_selector.go), instantiating only matching plugins.
- CLI flags (`--plugin-selector`) and configuration file sections (`[plugin_selector]`) provide flexible deployment options without modifying plugin definitions.

## Frequently Asked Questions

### How do I add labels to a specific Telegraf plugin instance?

Add a `[plugin_name.labels]` table within the plugin's configuration block in your TOML file. For example, under `[[inputs.cpu]]`, create a `[inputs.cpu.labels]` section with key-value pairs like `env = "prod"`. The Telegraf parser stores these as a `map[string]string` attached to that plugin's configuration.

### Can I use both include and exclude selectors simultaneously?

Yes. The selector logic in [`agent/agent.go`](https://github.com/influxdata/telegraf/blob/main/agent/agent.go) applies both filters: a plugin must satisfy all `selector_include` expressions and must not match any `selector_exclude` expressions to run. This allows complex scenarios like including all production plugins while excluding specific deprecated ones.

### What is the difference between label selectors and field selectors in Telegraf?

Label selectors match against custom metadata defined in `[plugin.labels]` tables (e.g., `env=prod`), while field selectors match against intrinsic plugin attributes like `type` or `version` (e.g., `type=output`). Both use the same Kubernetes selector syntax but target different data sources, with field selectors accessing plugin metadata beyond user-defined labels.

### Where does the selector matching logic execute in the Telegraf codebase?

The matching occurs in the `filterPlugins` function within [`agent/agent.go`](https://github.com/influxdata/telegraf/blob/main/agent/agent.go) during agent startup. This function iterates through parsed plugins, calling `Matches()` on compiled `labels.Selector` and `fields.Selector` objects created by [`config/plugin_selector.go`](https://github.com/influxdata/telegraf/blob/main/config/plugin_selector.go) using the `k8s.io/apimachinery` library.