From 1560b1bfe9938f01988c8122f1d7d92670d64eb0 Mon Sep 17 00:00:00 2001
From: Scott Anderson <sanderson@users.noreply.github.com>
Date: Mon, 22 Feb 2021 15:03:59 -0700
Subject: [PATCH] Add information about Telegraf processor/aggregator plugin
 behavior (#2174)

* add information about telegraf processor and aggreator plugin behavior, closes influxdata/DAR#174

* updated telegraf processor-aggregator doc to address PR feedback
---
 .../concepts/aggregator_processor_plugins.md  | 27 +++++++++++++++----
 .../concepts/aggregator_processor_plugins.md  | 17 ++++++++----
 2 files changed, 34 insertions(+), 10 deletions(-)

diff --git a/content/telegraf/v1.16/concepts/aggregator_processor_plugins.md b/content/telegraf/v1.16/concepts/aggregator_processor_plugins.md
index 4bbcbdc21..dcdece8b4 100644
--- a/content/telegraf/v1.16/concepts/aggregator_processor_plugins.md
+++ b/content/telegraf/v1.16/concepts/aggregator_processor_plugins.md
@@ -3,7 +3,7 @@ title: Telegraf aggregator and processor plugins
 description: Aggregator and processor plugins work between the input plugins and output plugins to aggregate and process metrics in Telegraf.
 menu:
   telegraf_1_16:
-    name: Aggregator and processor plugins
+    name: Aggregator & processor plugins
     weight: 20
     parent: Concepts
 ---
@@ -43,7 +43,24 @@ Since many users will only care about their aggregates and not every single metr
 gathered, there is also a `drop_original` argument, which tells Telegraf to only
 emit the aggregates and not the original metrics.
 
-**NOTE** Since aggregator plugins only aggregate metrics within their periods,
-historical data is not supported. In other words, if your metric timestamp is more
-than `now() - period` in the past, it will not be aggregated. If this is a feature
-that you need, please comment on this [GitHub issue](https://github.com/influxdata/telegraf/issues/1992).
+{{% note %}}
+#### Aggregator plugins do not support historical data
+Since aggregator plugins only aggregate metrics within their periods,
+historical data is not supported.
+In other words, if your metric timestamp is more
+than `now() - period` in the past, it is not aggregated.
+
+For more information, see [influxdata/telegraf#1992](https://github.com/influxdata/telegraf/issues/1992).
+{{% /note %}}
+
+{{% note %}}
+#### Behavior of processors and aggregators when used together
+When using both aggregator and processor plugins in Telegraf v1.17, processor plugins
+process data and then pass it to aggregator plugins.
+After aggregator plugins aggregate the data, they pass it back to processor plugins.
+This can have unintended consequences, such as executing mathematical operations twice.
+_See [influxdata/telegraf#7993](https://github.com/influxdata/telegraf/issues/7993)._
+
+If using custom processor scripts, they must be idempotent (repeatable, without side-effects).
+For custom processes that are not idempotent, use [namepass or namedrop](/telegraf/v1.17/administration/configuration/#input-config-namepass-and-namedrop) to avoid issues when aggregated data is processed a second time.
+{{% /note %}}
diff --git a/content/telegraf/v1.17/concepts/aggregator_processor_plugins.md b/content/telegraf/v1.17/concepts/aggregator_processor_plugins.md
index 7e5bc29ad..28fd92b98 100644
--- a/content/telegraf/v1.17/concepts/aggregator_processor_plugins.md
+++ b/content/telegraf/v1.17/concepts/aggregator_processor_plugins.md
@@ -3,7 +3,7 @@ title: Telegraf aggregator and processor plugins
 description: Aggregator and processor plugins work between the input plugins and output plugins to aggregate and process metrics in Telegraf.
 menu:
   telegraf_1_17:
-    name: Aggregator and processor plugins
+    name: Aggregator & processor plugins
     weight: 20
     parent: Concepts
 ---
@@ -43,7 +43,14 @@ Since many users will only care about their aggregates and not every single metr
 gathered, there is also a `drop_original` argument, which tells Telegraf to only
 emit the aggregates and not the original metrics.
 
-**NOTE** Since aggregator plugins only aggregate metrics within their periods,
-historical data is not supported. In other words, if your metric timestamp is more
-than `now() - period` in the past, it will not be aggregated. If this is a feature
-that you need, please comment on this [GitHub issue](https://github.com/influxdata/telegraf/issues/1992).
+{{% note %}}
+#### Behavior of processors and aggregators when used together
+When using both aggregator and processor plugins in Telegraf v1.17, processor plugins
+process data and then pass it to aggregator plugins.
+After aggregator plugins aggregate the data, they pass it back to processor plugins.
+This can have unintended consequences, such as executing mathematical operations twice.
+_See [influxdata/telegraf#7993](https://github.com/influxdata/telegraf/issues/7993)._
+
+If using custom processor scripts, they must be idempotent (repeatable, without side-effects).
+For custom processes that are not idempotent, use [namepass or namedrop](/telegraf/v1.17/administration/configuration/#input-config-namepass-and-namedrop) to avoid issues when aggregated data is processed a second time.
+{{% /note %}}