Telegraf Processor Plugins
Telegraf processor plugins transform individual metrics by e.g. converting tags and fields or data-types.
AWS EC2 Metadata
This plugin appends metadata gathered from AWS IMDS to metrics associated with EC2 instances.
Batch
This plugin groups metrics into batches by adding a batch tag. This is
useful for parallel processing of metrics where downstream processors,
aggregators or outputs can then select a batch using tagpass or
metricpass.
Metrics are distributed across batches using the round-robin scheme.
Clone
This plugin creates a copy of each metric passing through it, preserving the original metric and allowing modifications such as metric modifiers in the copied metric.
Metric filtering options apply to both the clone and the original metric.
Converter
This plugin allows transforming tags into fields or timestamps, and converting fields into tags or timestamps. The plugin furthermore allows to change the field type.
When converting tags to fields, take care to ensure the series is still uniquely identifiable. Fields with the same series key (measurement + tags) will overwrite one another.
Cumulative Sum
This plugin accumulates field values per-metric over time and emit metrics with cumulative sums whenever a metric is updated. This is useful when using outputs relying on monotonically increasing values
Metrics within a series are accumulated in the order of arrival and not in order of their timestamps!
Date
This plugin adds the metric timestamp as a human readable tag. A common use is to add a tag that can be used to group by month or year.
Dedup
This plugin filters metrics whose field values are exact repetitions of
the previous values. This plugin will store its state between runs if the
statefile option in the agent config section is set.
Defaults
This plugin allows to specify default values for fields and tags for cases where the tag or field does not exist or has an empty value.
Enum
This plugin allows the mapping of field or tag values according to the configured enumeration. The main use-case is to rewrite numerical values into human-readable values or vice versa. Default mappings can be configured to be used for all remaining values.
Execd
This plugin runs an external program as a separate process and pipes
metrics in to the process’s stdin and reads processed metrics from its
stdout. Program output on stderr is logged.
Filepath
This plugin allows transforming a path, using e.g. basename to extract the last path element, for tag and field values. Values can be modified in place or stored in another key.
Filter
This plugin allows specifying a set of rules for metrics with the ability to keep or drop those metrics. It does not modify the metric. As such a user might want to apply this processor to remove metrics from the processing/output stream.
The filtering is not output specific, but will apply to the metrics processed by this processor.
Network Interface Name
This plugin looks up network interface names using SNMP.
Lookup
This plugin allows to use one or more files containing lookup-tables for annotating incoming metrics. The lookup is static as the files are only used on startup. The main use-case for this is to annotate metrics with additional tags e.g. dependent on their source. Multiple tags can be added depending on the lookup-table files.
The lookup key can be generated using a Golang template with the ability
to access the metric name via {{.Name}}, the tag values via {{.Tag "mytag"}}, with mytag being the tag-name and field-values via
{{.Field "myfield"}}, with myfield being the field-name. Non-existing
tags and field will result in an empty string or nil respectively. In
case the key cannot be found, the metric is passed-through unchanged. By
default all matching tags are added and existing tag-values are
overwritten.
The plugin only supports the addition of tags and thus all mapped tag-values need to be strings!
Noise
This plugin is used to add noise to numerical field values. For each field a noise is generated using a defined probability density function and added to the value. The function type can be configured as Laplace, Gaussian or Uniform.
Override
This plugin allows to modify metrics using metric
modifiers. Use-cases of this
plugin encompass ensuring certain tags or naming conventions are adhered
to irrespective of input plugin configurations, e.g. by taginclude.
Metric filtering options apply to both the clone and the original metric.
Parser
This plugin parses defined fields or tags containing the specified data format and creates new metrics based on the resulting fields and tags.
Pivot
This plugin rotates single-valued metrics into a multi-field metric. The result is a more compact representation for applying mathematical operators to or do comparisons between metrics or flatten fields.
To perform the reverse operation use the unpivot processor.
Port Name Lookup
This plugin allows converting a tag or field containing a well-known
port, either a number (e.g. 80) for TCP ports or a port and protocol
(e.g. 443/tcp), to the registered service name.
Printer
This plugin prints every metric passing through it to the standard output.
Regex
This plugin transforms tag and field values as well as renaming tags, fields and metrics using regular expression patterns. Tag and field values can be transformed using named-groups in a batch fashion.
The regex processor only operates on string fields. It will not work on any other data types, like an integer or float.
Rename
This plugin allows to rename measurements, fields and tags.
Reverse DNS
This plugin does a reverse-dns lookup on tags or fields containing IPs and creates a tag or field containing the corresponding DNS name.
Round
This plugin allows to round numerical field values to the configured precision. This is particularly useful in combination with the dedup processor to reduce the number of metrics sent to the output if only a lower precision is required for the values.
S2 Geo
This plugin uses the WGS-84 coordinates in decimal degrees specified in the latitude and longitude fields and adds a tag with the corresponding S2 cell ID token of specified cell level.
Scale
This plugin allows to scale field-values from an input range into the given output range according to this formula:
Alternatively, you can apply a factor and offset to the input according to this formula
Input fields are converted to floating point values if possible. Otherwise, fields that cannot be converted are ignored and keep their original value.
Neither the input nor output values are clipped to their respective ranges!
SNMP Lookup
This plugin looks up extra information via SNMP and adds it to the metric as tags.
Split
This plugin splits a metric up into one or more metrics based on a configured template. The resulting metrics will be timestamped according to the source metric. Templates can overlap, where a field or tag, is used across templates and as a result end up in multiple metrics.
If drop original is changed to true, then the plugin can result in dropping all metrics when no match is found! Please ensure to test templates before putting into production and use metric filtering to avoid data loss.
Starlark
This plugin calls the provided Starlark function for each matched metric, allowing for custom programmatic metric processing.
The Starlark language is a dialect of Python, and will be familiar to those who have experience with the Python language. However, there are major differences. Existing Python code is unlikely to work unmodified. The execution environment is sandboxed, and it is not possible to do I/O operations such as reading from files or sockets.
The Starlark specification has details about the syntax and available functions.
Strings
This plugin allows to manipulate strings in the measurement name, tag and field values using different functions.
Tag Limit
This plugin ensures that only a certain number of tags are preserved for any given metric, and to choose the tags to preserve when the number of tags appended by the data source is over the limit.
This can be useful when dealing with output systems (e.g. Stackdriver) that impose hard limits on the number of tags/labels per metric or where high levels of cardinality are computationally and/or financially expensive.
Template
This plugin applies templates to metrics for generating a new tag. The primary use case of this plugin is to create a tag that can be used for dynamic routing to multiple output plugins or using an output specific routing option.
The template has access to each metric’s measurement name, tags, fields, and timestamp. Templates follow the Go Template syntax and may contain Sprig functions.
Timestamp
This plugin allows to parse fields containing timestamps into timestamps of other format.
TopK
This plugin filters the top series over a period of time and calculates
the top metrics via different aggregation functions. The processing steps
comprise grouping the metrics based on the metric name and tags,
computing the aggregate functions for each group every period and
outputting the top K groups.
Unpivot
This plugin allows to rotate a multi-field series into single-valued metrics. The resulting metrics allow to more easily aggregate data across fields.
To perform the reverse operation use the pivot processor.
Was this page helpful?
Thank you for your feedback!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for Telegraf and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support.