From 9ace2a5a84834ecfd86ada3d165d60e948580fa4 Mon Sep 17 00:00:00 2001 From: Joshua Powers Date: Tue, 14 May 2024 04:33:30 -0600 Subject: [PATCH] docs: Update aggregator and processor docs (#15343) --- docs/AGGREGATORS_AND_PROCESSORS.md | 56 +++++++++++++++++++++--------- docs/CONFIGURATION.md | 4 +++ 2 files changed, 44 insertions(+), 16 deletions(-) diff --git a/docs/AGGREGATORS_AND_PROCESSORS.md b/docs/AGGREGATORS_AND_PROCESSORS.md index 389138cec..aa39b01f1 100644 --- a/docs/AGGREGATORS_AND_PROCESSORS.md +++ b/docs/AGGREGATORS_AND_PROCESSORS.md @@ -1,9 +1,8 @@ -# Telegraf Aggregator & Processor Plugins +# Aggregator & Processor Plugins -As of release 1.1.0, Telegraf has the concept of Aggregator and Processor Plugins. - -These plugins sit in-between Input & Output plugins, aggregating and processing -metrics as they pass through Telegraf: +Telegraf has the concept of aggregator and processor plugins, which sit between +inputs and outputs. These plugins allow a user to do additional processing or +aggregation to collected metrics. ```text ┌───────────┐ @@ -37,12 +36,26 @@ metrics as they pass through Telegraf: └───────────┘ ``` -Both Aggregators and Processors analyze metrics as they pass through Telegraf. +## Ordering -Use [measurement filtering](CONFIGURATION.md#measurement-filtering) -to control which metrics are passed through a processor or aggregator. If a -metric is filtered out the metric bypasses the plugin and is passed downstream -to the next plugin. +Processors are run first, then aggregators, then processors a second time. + +Allowing processors to run again after aggregators gives users the opportunity +to run a processor on any aggregated metrics. This behavior can be a bit +surprising to new users and may cause weird behavior in metrics. For example, +if the user scales data, it could get scaled twice! + +To disable this behavior set the `skip_processors_after_aggregators` agent +configuration setting to true. Another option is to use metric filtering as +described below. + +## Metric Filtering + +Use [metric filtering][] to control which metrics are passed through a processor +or aggregator. If a metric is filtered out the metric bypasses the plugin and +is passed downstream to the next plugin. + +[metric filtering]: CONFIGURATION.md#measurement-filtering ## Processor @@ -50,6 +63,10 @@ Processor plugins process metrics as they pass through and immediately emit results based on the values they process. For example, this could be printing all metrics or adding a tag to all metrics that pass through. +See the [processors][] for a full list of processor plugins available. + +[processors]: https://github.com/influxdata/telegraf/tree/master/plugins/processors + ## Aggregator Aggregator plugins, on the other hand, are a bit more complicated. Aggregators @@ -58,12 +75,19 @@ minimum, maximum, or standard deviation. For this reason, all _aggregator_ plugins are configured with a `period`. The `period` is the size of the window of metrics that each _aggregate_ represents. In other words, the emitted _aggregate_ metric will be the aggregated value of the past `period` seconds. -Since many users will only care about their aggregates and not every single metric -gathered, there is also a `drop_original` argument, which tells Telegraf to only -emit the aggregates and not the original metrics. -Since aggregates are created for each measurement, field, and unique tag combination -the plugin receives, you can make use of `taginclude` to group +Since many users will only care about their aggregates and not every single +metric gathered, there is also a `drop_original` argument, which tells Telegraf +to only emit the aggregates and not the original metrics. + +Since aggregates are created for each measurement, field, and unique tag +combination the plugin receives, you can make use of `taginclude` to group aggregates by specific tags only. -**Note:** Aggregator plugins only aggregate metrics within their periods (`now() - period`). Data with a timestamp earlier than `now() - period` cannot be included. +See the [aggregators][] for a full list of aggregator plugins available. + +**Note:** Aggregator plugins only aggregate metrics within their periods +(i.e. `now() - period`). Data with a timestamp earlier than `now() - period` +cannot be included. + +[aggregators]: https://github.com/influxdata/telegraf/tree/master/plugins/aggregators diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 674ad68cc..26ba59a06 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -348,6 +348,10 @@ The agent table configures Telegraf and the defaults used across all plugins. tag-filtering via `taginclude` or `tagexclude`. This removes the need to specify those tags twice. +- **skip_processors_after_aggregators**: + By default, processors are run a second time after aggregators. Changing + this setting to true will skip the second run of processors. + ## Plugins Telegraf plugins are divided into 4 types: [inputs][], [outputs][],