Telegraf Aggregator Plugins

Basic Statistics

Plugin ID: aggregators.basicstats
Telegraf v1.5.0+

This plugin computes basic statistics such as counts, differences, minima, maxima, mean values, non-negative differences etc. for a set of metrics and emits these statistical values every period.

Derivative

Plugin ID: aggregators.derivative
Telegraf v1.18.0+

This plugin computes the derivative for all fields of the aggregated metrics.

Final

Plugin ID: aggregators.final
Telegraf v1.11.0+

This plugin emits the last metric of a contiguous series, defined as a series which receives updates within the time period in series_timeout. The contiguous series may be longer than the time interval defined by period. When a series has not been updated within the series_timeout, the last metric is emitted.

Alternatively, the plugin emits the last metric in the period for the periodic output strategy.

This is useful for getting the final value for data sources that produce discrete time series such as procstat, cgroup, kubernetes etc. or to downsample metrics collected at a higher frequency.

Histogram

Plugin ID: aggregators.histogram
Telegraf v1.4.0+

This plugin creates histograms containing the counts of field values within the configured range. The histogram metric is emitted every period.

In cumulative mode, values added to a bucket are also added to the consecutive buckets in the distribution creating a cumulative histogram.

Merge

Plugin ID: aggregators.merge
Telegraf v1.13.0+

This plugin merges metrics of the same series and timestamp into new metrics with the super-set of fields. A series here is defined by the metric name and the tag key-value set.

Use this plugin when fields are split over multiple metrics, with the same measurement, tag set and timestamp.

Minimum-Maximum

Plugin ID: aggregators.minmax
Telegraf v1.1.0+

This plugin aggregates the minimum and maximum values of each field it sees, emitting the aggrate every period seconds with field names suffixed by _min and _max respectively.

Quantile

Plugin ID: aggregators.quantile
Telegraf v1.18.0+

This plugin aggregates each numeric field per metric into the specified quantiles and emits the quantiles every period. Different aggregation algorithms are supported with varying accuracy and limitations.

Starlark

Plugin ID: aggregators.starlark
Telegraf v1.21.0+

This plugin allows to implement a custom aggregator plugin via a Starlark script.

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 Starlark script used by this plugin needs to be composed of the three methods defining an aggreagtor named add, push and reset.

The add method is called as soon as a new metric is added to the plugin the metrics to the aggregator. After period, the push method is called to output the resulting metrics and finally the aggregation is reset by using the reset method of the Starlark script.

The Starlark functions might use the global function state to keep aggregation information such as added metrics etc.

More details on the syntax and available functions can be found in the Starlark specification.

Value Counter

Plugin ID: aggregators.valuecounter
Telegraf v1.8.0+

This plugin counts the occurrence of unique values in fields and emits the counter once every period with the field-names being suffixed by the unique value converted to string.

This plugin is useful to e.g. count the occurrances of HTTP status codes or other categorical values in the defined period.