Telegraf Controller glossary

This glossary defines terms you encounter when working with Telegraf Controller. Some terms describe Telegraf Controller concepts such as labels, reporting rules, and the heartbeat protocol. Others describe Telegraf concepts that Telegraf Controller surfaces in its UI and API. For deeper background on Telegraf agent internals, see the Telegraf glossary.

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

A

agent

In Telegraf Controller, an agent is a Telegraf process that is registered with Controller and periodically sends a heartbeat reporting its status, version, hostname, and the configurations it is running. Each agent is identified by an agent_id set in the Telegraf configuration. Agents appear in the Telegraf Controller UI and can be grouped with labels and governed by reporting rules.

Related entries: heartbeat, instance, label, reporting rule, reporting status, Telegraf agent

aggregator plugin

A Telegraf plugin that receives metrics from input plugins and produces aggregate metrics (such as sums, averages, or histograms) over a configurable time window before passing them to output plugins. Aggregator plugins appear as a configurable category in the Telegraf Controller configuration builder.

Related entries: input plugin, output plugin, processor plugin, Telegraf aggregator plugin

C

collection interval

The frequency at which a Telegraf input plugin collects metrics from its source, for example every 10 seconds. The global collection interval is set in the [agent] section of a Telegraf configuration and can be overridden per input plugin.

Related entries: flush interval, input plugin, Telegraf collection interval

configuration

A TOML document that defines which inputs, outputs, processors, aggregators, and secret stores a Telegraf agent should run, along with the settings for each. Telegraf Controller stores configurations centrally and delivers them to agents that request them. The terms config and configuration are used interchangeably in the Telegraf Controller UI and API.

Related entries: configuration parameter, environment variable, plugin, secret, TOML

configuration parameter

A placeholder of the form &{param_name[:default_value]} embedded in a configuration’s TOML. When an agent requests a configuration, Telegraf Controller substitutes parameter values from the request’s URL query string before returning the rendered TOML. Parameters let you deliver one configuration to many agents with per-agent values. Parameters are a Telegraf Controller feature and are not part of the Telegraf project.

Related entries: configuration, environment variable, secret

E

environment variable

A placeholder of the form ${VAR} or ${VAR:-default} in a Telegraf configuration. Environment variables are resolved by the Telegraf agent from its own runtime environment when the agent starts, after Telegraf Controller has rendered any configuration parameters. Use environment variables for values supplied by the host running Telegraf, such as credentials or host-specific identifiers.

Related entries: configuration, configuration parameter, secret

F

field

A key-value pair in a Telegraf metric that holds a measured value, for example usage_idle=98.2. Fields carry the data; they are typically not used as filterable dimensions. Use tags for filterable dimensions.

Related entries: measurement, metric, tag

flush interval

The frequency at which a Telegraf output plugin sends batched metrics to its destination. The flush interval is set in the [agent] section of a Telegraf configuration and applies globally to all output plugins. It should not be smaller than the collection interval.

Related entries: collection interval, output plugin, Telegraf flush interval

H

heartbeat

A periodic HTTP request that a Telegraf agent sends to Telegraf Controller to report that it is alive, what version it is running, and which configurations it is using. Telegraf Controller processes heartbeats through a dedicated high-performance server and uses them to maintain each agent’s reporting status. A heartbeat may also include Telegraf runtime statistics that drive agent status evaluation.

Related entries: agent, reporting rule, reporting status

I

input plugin

A Telegraf plugin that collects metrics from a source system, such as CPU, memory, disk, an HTTP endpoint, or a message broker. Input plugins appear as a configurable category in the Telegraf Controller configuration builder.

Related entries: aggregator plugin, collection interval, output plugin, processor plugin, Telegraf input plugin

instance

The word instance has two meanings in Telegraf Controller documentation, depending on context:

• Telegraf agent instance: a running Telegraf process. Each agent registered with Telegraf Controller is one Telegraf instance. When multiple Telegraf processes run on the same host, each is a separate instance with its own agent_id.
• Telegraf Controller instance: a running Telegraf Controller server. An instance is the deployed application that manages a fleet of Telegraf agents, including the web UI, API server, and heartbeat server.

Related entries: agent, architecture

L

label

The word label has two meanings, depending on context:

• Telegraf Controller label: a user-defined tag that you attach to agents and configurations to group, filter, and find them in the UI. Telegraf Controller labels can have a color for visual distinction and are unrelated to Telegraf metric tags.
• Telegraf agent label: a marker placed on a plugin in a Telegraf configuration that lets you enable or disable that plugin from the Telegraf command line using selectors. Use Telegraf agent labels to toggle plugins on or off without editing the configuration.

Related entries: agent, configuration, plugin, tag

M

measurement

The name of a Telegraf metric, for example cpu or mem. A measurement groups related fields and tags and typically becomes the table or series name in the destination system.

Related entries: field, metric, tag

metric

A data point produced by a Telegraf input plugin. A metric has a measurement name, one or more fields, zero or more tags, and a timestamp.

Related entries: field, input plugin, measurement, tag

O

output plugin

A Telegraf plugin that sends collected metrics to a destination, such as InfluxDB, Kafka, or a file. Output plugins appear as a configurable category in the Telegraf Controller configuration builder.

Related entries: aggregator plugin, flush interval, input plugin, processor plugin, Telegraf output plugin

P

plugin

A modular component of Telegraf that performs one job in the metric pipeline: input plugins collect metrics, processor plugins transform them, aggregator plugins summarize them, and output plugins send them to a destination. Secret stores are a related plugin type for managing sensitive values. Telegraf Controller exposes plugins as the building blocks of the configuration builder.

Related entries: aggregator plugin, configuration, input plugin, output plugin, processor plugin, secret store

processor plugin

A Telegraf plugin that modifies, filters, or enriches metrics in the pipeline between collection and output. Processor plugins appear as a configurable category in the Telegraf Controller configuration builder.

Related entries: aggregator plugin, input plugin, output plugin, Telegraf processor plugin

R

reporting rule

A Telegraf Controller policy that defines how often an agent is expected to send heartbeats and how long Controller waits before marking the agent as not reporting. A reporting rule can also configure automatic deletion of agents that have not reported for a specified period. You can assign reporting rules to agents individually or by label.

Related entries: agent, heartbeat, label, reporting status, reporting rules

reporting status

The health state that Telegraf Controller assigns to each agent based on its heartbeats and (optionally) the runtime statistics those heartbeats carry. The status takes one of six values:

• Ok: the agent is reporting normally and any configured status evaluation passes.
• Warn: status evaluation indicates a non-critical issue.
• Fail: status evaluation indicates a critical issue.
• Error: the agent is reporting but is itself in an error state.
• Not reporting: the agent has not sent a heartbeat within the threshold defined by its reporting rule.
• Undefined: no status has been determined yet, typically because the agent has just registered.

The Warn, Fail, and Ok values are driven by agent status evaluation expressions defined in the Telegraf outputs.heartbeat plugin.

Related entries: agent, heartbeat, reporting rule

S

secret

A sensitive value, such as an API token or password, that a Telegraf plugin needs at runtime. Secrets are referenced from a configuration using the syntax @{store_id:key} and resolved by a secret store. Using a secret keeps the sensitive value out of the configuration TOML and out of Telegraf Controller.

Related entries: configuration parameter, environment variable, secret store

secret store

A Telegraf plugin type that supplies sensitive values to other plugins on demand. Secret stores include OS keyrings, files, and external secret managers. Telegraf Controller lets you declare secret stores in a configuration; the resolution happens entirely on the Telegraf agent at runtime.

Related entries: configuration, plugin, secret

T

tag

A key-value pair attached to a Telegraf metric that is used as a dimension for grouping and filtering, for example host=server-1 or region=us-east. Tags are part of the Telegraf metric model and are distinct from Telegraf Controller labels.

Related entries: field, label, measurement, metric

TOML

Tom’s Obvious, Minimal Language, the file format Telegraf uses for its configuration. Telegraf Controller’s configuration builder produces TOML, and the API can return any configuration as a rendered TOML document.

Related entries: configuration

token

A credential issued by Telegraf Controller that authenticates API requests and agent communications. Tokens are scoped by role and can be revoked or reassigned. For details, see Authorization.

Related entries: agent, authorization