--- title: Telegraf Processor Plugins description: Telegraf processor plugins transform individual metrics. url: https://docs.influxdata.com/telegraf/v1/processor-plugins/ estimated_tokens: 6196 product: Telegraf version: v1 --- # Telegraf Processor Plugins Telegraf processor plugins transform individual metrics by e.g. converting tags and fields or data-types. ### AWS EC2 Metadata Plugin ID: `processors.aws_ec2` Telegraf v1.18.0+ This plugin appends metadata gathered from [AWS IMDS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) to metrics associated with EC2 instances. [View](/telegraf/v1/processor-plugins/aws_ec2/) ### Batch Plugin ID: `processors.batch` Telegraf v1.33.0+ 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. [View](/telegraf/v1/processor-plugins/batch/) ### Clone Plugin ID: `processors.clone` Telegraf v1.13.0+ This plugin creates a copy of each metric passing through it, preserving the original metric and allowing modifications such as [metric modifiers](/telegraf/v1/configuration/#modifiers) in the copied metric. [Metric filtering](/telegraf/v1/configuration/#metric-filtering) options apply to both the clone and the original metric. [View](/telegraf/v1/processor-plugins/clone/) ### Converter Plugin ID: `processors.converter` Telegraf v1.7.0+ 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. [View](/telegraf/v1/processor-plugins/converter/) ### Cumulative Sum Plugin ID: `processors.cumulative_sum` Telegraf v1.35.0+ 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! [View](/telegraf/v1/processor-plugins/cumulative_sum/) ### Date Plugin ID: `processors.date` Telegraf v1.12.0+ 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. [View](/telegraf/v1/processor-plugins/date/) ### Dedup Plugin ID: `processors.dedup` Telegraf v1.14.0+ 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. [View](/telegraf/v1/processor-plugins/dedup/) ### Defaults Plugin ID: `processors.defaults` Telegraf v1.15.0+ 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. [View](/telegraf/v1/processor-plugins/defaults/) ### Enum Plugin ID: `processors.enum` Telegraf v1.8.0+ 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. [View](/telegraf/v1/processor-plugins/enum/) ### Execd Plugin ID: `processors.execd` Telegraf v1.15.0+ 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. [View](/telegraf/v1/processor-plugins/execd/) ### Filepath Plugin ID: `processors.filepath` Telegraf v1.15.0+ 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. [View](/telegraf/v1/processor-plugins/filepath/) ### Filter Plugin ID: `processors.filter` Telegraf v1.29.0+ 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. [View](/telegraf/v1/processor-plugins/filter/) ### Network Interface Name Plugin ID: `processors.ifname` Telegraf v1.15.0+ This plugin looks up network interface names using SNMP. [View](/telegraf/v1/processor-plugins/ifname/) ### Lookup Plugin ID: `processors.lookup` Telegraf v1.15.0+ 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! [View](/telegraf/v1/processor-plugins/lookup/) ### Noise Plugin ID: `processors.noise` Telegraf v1.22.0+ 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*. [View](/telegraf/v1/processor-plugins/noise/) ### Override Plugin ID: `processors.override` Telegraf v1.6.0+ This plugin allows to modify metrics using [metric modifiers](/telegraf/v1/configuration/#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](/telegraf/v1/configuration/#metric-filtering) options apply to both the clone and the original metric. [View](/telegraf/v1/processor-plugins/override/) ### Parser Plugin ID: `processors.parser` Telegraf v1.8.0+ This plugin parses defined fields or tags containing the specified [data format](/telegraf/v1/data_formats/input) and creates new metrics based on the resulting fields and tags. [View](/telegraf/v1/processor-plugins/parser/) ### Pivot Plugin ID: `processors.pivot` Telegraf v1.12.0+ 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](/telegraf/v1/plugins/#processor-unpivot) processor. [View](/telegraf/v1/processor-plugins/pivot/) ### Port Name Lookup Plugin ID: `processors.port_name` Telegraf v1.15.0+ 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. [View](/telegraf/v1/processor-plugins/port_name/) ### Printer Plugin ID: `processors.printer` Telegraf v1.1.0+ This plugin prints every metric passing through it to the standard output. [View](/telegraf/v1/processor-plugins/printer/) ### Regex Plugin ID: `processors.regex` Telegraf v1.7.0+ 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. [View](/telegraf/v1/processor-plugins/regex/) ### Rename Plugin ID: `processors.rename` Telegraf v1.8.0+ This plugin allows to rename measurements, fields and tags. [View](/telegraf/v1/processor-plugins/rename/) ### Reverse DNS Plugin ID: `processors.reverse_dns` Telegraf v1.15.0+ This plugin does a reverse-dns lookup on tags or fields containing IPs and creates a tag or field containing the corresponding DNS name. [View](/telegraf/v1/processor-plugins/reverse_dns/) ### Round Plugin ID: `processors.round` Telegraf v1.36.0+ This plugin allows to round numerical field values to the configured precision. This is particularly useful in combination with the [dedup processor](/telegraf/v1/plugins/#processor-dedup) to reduce the number of metrics sent to the output if only a lower precision is required for the values. [View](/telegraf/v1/processor-plugins/round/) ### S2 Geo Plugin ID: `processors.s2geo` Telegraf v1.14.0+ 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](https://s2geometry.io/resources/s2cell_statistics.html). [View](/telegraf/v1/processor-plugins/s2geo/) ### Scale Plugin ID: `processors.scale` Telegraf v1.27.0+ 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! [View](/telegraf/v1/processor-plugins/scale/) ### SNMP Lookup Plugin ID: `processors.snmp_lookup` Telegraf v1.30.0+ This plugin looks up extra information via SNMP and adds it to the metric as tags. [View](/telegraf/v1/processor-plugins/snmp_lookup/) ### Split Plugin ID: `processors.split` Telegraf v1.28.0+ 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. [View](/telegraf/v1/processor-plugins/split/) ### Starlark Plugin ID: `processors.starlark` Telegraf v1.15.0+ 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](https://github.com/google/starlark-go/blob/d1966c6b9fcd/doc/spec.md)** has details about the syntax and available functions. [View](/telegraf/v1/processor-plugins/starlark/) ### Strings Plugin ID: `processors.strings` Telegraf v1.8.0+ This plugin allows to manipulate strings in the measurement name, tag and field values using different functions. [View](/telegraf/v1/processor-plugins/strings/) ### Tag Limit Plugin ID: `processors.tag_limit` Telegraf v1.12.0+ 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. [View](/telegraf/v1/processor-plugins/tag_limit/) ### Template Plugin ID: `processors.template` Telegraf v1.14.0+ 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](https://golang.org/pkg/text/template/) and may contain [Sprig functions](http://masterminds.github.io/sprig/). [View](/telegraf/v1/processor-plugins/template/) ### Timestamp Plugin ID: `processors.timestamp` Telegraf v1.31.0+ This plugin allows to parse fields containing timestamps into timestamps of other format. [View](/telegraf/v1/processor-plugins/timestamp/) ### TopK Plugin ID: `processors.topk` Telegraf v1.7.0+ 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. [View](/telegraf/v1/processor-plugins/topk/) ### Unpivot Plugin ID: `processors.unpivot` Telegraf v1.12.0+ 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](/telegraf/v1/plugins/#processor-pivot) processor. [View](/telegraf/v1/processor-plugins/unpivot/)