How Telegraf Plugin Labels and Selectors Enable Selective Plugin Loading

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:

[[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:

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

Via CLI:

telegraf --plugin-selector "env=prod"

The Runtime Filtering Mechanism

The selective loading process occurs during agent startup in agent/agent.go, where the filterPlugins function applies parsed selectors against plugin label sets.

Parsing Selectors

The 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:

// 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, the filterPlugins routine evaluates each plugin:

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:

telegraf --plugin-selector "env=prod"

Or in configuration:

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

Excluding Deprecated Plugins

Prevent loading of deprecated plugin instances:

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

Complex Include and Exclude Logic

Combine selectors for precise control:

[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 evaluates selectors against label sets after parsing via 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 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 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 using the k8s.io/apimachinery library.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}