Add detailed plugin documentation for Telegraf v1.36.1

content/telegraf/v1/aggregator-plugins/_index.md

@@ -0,0 +1,16 @@
+---
+title: "Telegraf Aggregator Plugins"
+description: "Telegraf aggregator plugins aggregate data across multiple metrics."
+menu:
+  telegraf_v1_ref:
+    name: Aggregator plugins
+    parent: plugins_reference
+    identifier: aggregator_plugins_reference
+    weight: 10
+tags: [aggregator-plugins]
+---
+
+Telegraf aggregator plugins aggregate data across multiple metrics.
+Aggregator plugins create aggregate metrics--for example, by implementing statistical functions such as mean, min, and max.
+
+{{< telegraf/plugins type="aggregator" >}}

content/telegraf/v1/aggregator-plugins/basicstats/_index.md

@@ -0,0 +1,89 @@
+---
+description: "Telegraf plugin for aggregating metrics using Basic Statistics"
+menu:
+  telegraf_v1_ref:
+    parent: aggregator_plugins_reference
+    name: Basic Statistics
+    identifier: aggregator-basicstats
+tags: [Basic Statistics, "aggregator-plugins", "configuration", "statistics"]
+introduced: "v1.5.0"
+os_support: "freebsd, linux, macos, solaris, windows"
+related:
+  - /telegraf/v1/configure_plugins/
+  - https://github.com/influxdata/telegraf/tree/v1.36.1/plugins/aggregators/basicstats/README.md, Basic Statistics Plugin Source
+---
+
+# Basic Statistics Aggregator Plugin
+
+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`.
+
+**Introduced in:** Telegraf v1.5.0
+**Tags:** statistics
+**OS support:** all
+
+## Global configuration options <!-- @/docs/includes/plugin_config.md -->
+
+In addition to the plugin-specific configuration settings, plugins support
+additional global and plugin configuration settings. These settings are used to
+modify metrics, tags, and field or create aliases and configure ordering, etc.
+See the [CONFIGURATION.md](/telegraf/v1/configuration/#plugins) for more details.
+
+[CONFIGURATION.md]: ../../../docs/CONFIGURATION.md#plugins
+
+## Configuration
+
+```toml @sample.conf
+# Keep the aggregate basicstats of each metric passing through.
+[[aggregators.basicstats]]
+  ## The period on which to flush & clear the aggregator.
+  # period = "30s"
+
+  ## If true, the original metric will be dropped by the
+  ## aggregator and will not get sent to the output plugins.
+  # drop_original = false
+
+  ## Configures which basic stats to push as fields
+  # stats = ["count","min","max","mean","variance","stdev"]
+```
+
+- stats
+  - If not specified, then `count`, `min`, `max`, `mean`, `stdev`, and `s2` are
+  aggregated and pushed as fields. Other fields are not aggregated by default
+  to maintain backwards compatibility.
+  - If empty array, no stats are aggregated
+
+## Measurements & Fields
+
+- measurement1
+  - field1_count
+  - field1_diff (difference)
+  - field1_rate (rate per second)
+  - field1_max
+  - field1_min
+  - field1_mean
+  - field1_non_negative_diff (non-negative difference)
+  - field1_non_negative_rate (non-negative rate per second)
+  - field1_percent_change
+  - field1_sum
+  - field1_s2 (variance)
+  - field1_stdev (standard deviation)
+  - field1_interval (interval in nanoseconds)
+  - field1_last (last aggregated value)
+  - field1_first (first aggregated value)
+
+## Tags
+
+No tags are applied by this aggregator.
+
+## Example Output
+
+```text
+system,host=tars load1=1 1475583980000000000
+system,host=tars load1=1 1475583990000000000
+system,host=tars load1_count=2,load1_diff=0,load1_rate=0,load1_max=1,load1_min=1,load1_mean=1,load1_sum=2,load1_s2=0,load1_stdev=0,load1_interval=10000000000i,load1_last=1 1475584010000000000
+system,host=tars load1=1 1475584020000000000
+system,host=tars load1=3 1475584030000000000
+system,host=tars load1_count=2,load1_diff=2,load1_rate=0.2,load1_max=3,load1_min=1,load1_mean=2,load1_sum=4,load1_s2=2,load1_stdev=1.414162,load1_interval=10000000000i,load1_last=3,load1_first=3 1475584010000000000
+```

content/telegraf/v1/aggregator-plugins/derivative/_index.md

@@ -0,0 +1,146 @@
+---
+description: "Telegraf plugin for aggregating metrics using Derivative"
+menu:
+  telegraf_v1_ref:
+    parent: aggregator_plugins_reference
+    name: Derivative
+    identifier: aggregator-derivative
+tags: [Derivative, "aggregator-plugins", "configuration", "math"]
+introduced: "v1.18.0"
+os_support: "freebsd, linux, macos, solaris, windows"
+related:
+  - /telegraf/v1/configure_plugins/
+  - https://github.com/influxdata/telegraf/tree/v1.36.1/plugins/aggregators/derivative/README.md, Derivative Plugin Source
+---
+
+# Derivative Aggregator Plugin
+
+This plugin computes the derivative for all fields of the aggregated metrics.
+
+**Introduced in:** Telegraf v1.18.0
+**Tags:** math
+**OS support:** all
+
+## Global configuration options <!-- @/docs/includes/plugin_config.md -->
+
+In addition to the plugin-specific configuration settings, plugins support
+additional global and plugin configuration settings. These settings are used to
+modify metrics, tags, and field or create aliases and configure ordering, etc.
+See the [CONFIGURATION.md](/telegraf/v1/configuration/#plugins) for more details.
+
+[CONFIGURATION.md]: ../../../docs/CONFIGURATION.md#plugins
+
+## Configuration
+
+```toml @sample.conf
+# Calculates a derivative for every field.
+[[aggregators.derivative]]
+  ## The period in which to flush the aggregator.
+  # period = "30s"
+
+  ## Suffix to append for the resulting derivative field.
+  # suffix = "_rate"
+
+  ## Field to use for the quotient when computing the derivative.
+  ## When using a field as the derivation parameter the name of that field will
+  ## be used for the resulting derivative, e.g. *fieldname_by_parameter*.
+  ## By default the timestamps of the metrics are used and the suffix is omitted.
+  # variable = ""
+
+  ## Maximum number of roll-overs in case only one measurement is found during a period.
+  # max_roll_over = 10
+```
+
+This aggregator will estimate a derivative for each field of a metric, which is
+contained in both the first and last metric of the aggregation interval.
+Without further configuration the derivative will be calculated with respect to
+the time difference between these two measurements in seconds.
+The following formula is applied is for every field
+
+```text
+derivative = (value_last - value_first) / (time_last - time_first)
+```
+
+The resulting derivative will be named `<fieldname>_rate` if no `suffix` is
+configured.
+
+To calculate a derivative for every field use
+
+```toml
+[[aggregators.derivative]]
+  ## Specific Derivative Aggregator Arguments:
+
+  ## Configure a custom derivation variable. Timestamp is used if none is given.
+  # variable = ""
+
+  ## Suffix to add to the field name for the derivative name.
+  # suffix = "_rate"
+
+  ## Roll-Over last measurement to first measurement of next period
+  # max_roll_over = 10
+
+  ## General Aggregator Arguments:
+
+  ## calculate derivative every 30 seconds
+  period = "30s"
+```
+
+## Time Derivatives
+
+In its default configuration it determines the first and last measurement of
+the period. From these measurements the time difference in seconds is
+calculated. This time difference is than used to divide the difference of each
+field using the following formula:
+
+```text
+derivative = (value_last - value_first) / (time_last - time_first)
+```
+
+For each field the derivative is emitted with a naming pattern
+`<fieldname>_rate`.
+
+## Custom Derivation Variable
+
+The plugin supports to use a field of the aggregated measurements as derivation
+variable in the denominator. This variable is assumed to be a monotonically
+increasing value. In this feature the following formula is used:
+
+```text
+derivative = (value_last - value_first) / (variable_last - variable_first)
+```
+
+**Make sure the specified variable is not filtered and exists in the metrics
+passed to this aggregator!**
+
+When using a custom derivation variable, you should change the `suffix` of the
+derivative name.  See the next section on customizing the derivative
+name |
+| 16        |  4.0  |                     |             |                     |             |
+| 18        |  2.0  |                     |             |                     |             |
+| 20        |  0.0  |                     |             |                     |             |
+||| -1.0 | -1.0 | | |
+
+The difference stems from the change of the value between periods, e.g. from 6.0
+to 8.0 between first and second period.  Those changes are omitted with
+`max_roll_over = 0` but are respected with `max_roll_over = 1`.  That there are
+no more differences in the calculated derivatives is due to the example data,
+which has constant derivatives in during the first and last period, even when
+including the gap between the periods.  Using `max_roll_over` with a value
+greater 0 may be important, if you need to detect changes between periods,
+e.g. when you have very few measurements in a period or quasi-constant metrics
+with only occasional changes.
+
+### Tags
+
+No tags are applied by this aggregator.
+Existing tags are passed through the aggregator untouched.
+
+## Example Output
+
+```text
+net bytes_recv=15409i,packets_recv=164i,bytes_sent=16649i,packets_sent=120i 1508843640000000000
+net bytes_recv=73987i,packets_recv=364i,bytes_sent=87328i,packets_sent=452i 1508843660000000000
+net bytes_recv_by_packets_recv=292.89 1508843660000000000
+net packets_sent_rate=16.6,bytes_sent_rate=3533.95 1508843660000000000
+net bytes_sent_by_packet=292.89 1508843660000000000
+```

content/telegraf/v1/aggregator-plugins/final/_index.md

@@ -0,0 +1,107 @@
+---
+description: "Telegraf plugin for aggregating metrics using Final"
+menu:
+  telegraf_v1_ref:
+    parent: aggregator_plugins_reference
+    name: Final
+    identifier: aggregator-final
+tags: [Final, "aggregator-plugins", "configuration", "sampling"]
+introduced: "v1.11.0"
+os_support: "freebsd, linux, macos, solaris, windows"
+related:
+  - /telegraf/v1/configure_plugins/
+  - https://github.com/influxdata/telegraf/tree/v1.36.1/plugins/aggregators/final/README.md, Final Plugin Source
+---
+
+# Final Aggregator Plugin
+
+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.
+
+> [!NOTE]
+> All emited metrics do have fields with `_final` appended to the field-name
+> by default.
+
+**Introduced in:** Telegraf v1.11.0
+**Tags:** sampling
+**OS support:** all
+
+## Global configuration options <!-- @/docs/includes/plugin_config.md -->
+
+In addition to the plugin-specific configuration settings, plugins support
+additional global and plugin configuration settings. These settings are used to
+modify metrics, tags, and field or create aliases and configure ordering, etc.
+See the [CONFIGURATION.md](/telegraf/v1/configuration/#plugins) for more details.
+
+[CONFIGURATION.md]: ../../../docs/CONFIGURATION.md#plugins
+
+## Configuration
+
+```toml @sample.conf
+# Report the final metric of a series
+[[aggregators.final]]
+  ## The period on which to flush & clear the aggregator.
+  # period = "30s"
+
+  ## If true, the original metric will be dropped by the
+  ## aggregator and will not get sent to the output plugins.
+  # drop_original = false
+
+  ## If false, _final is added to every field name
+  # keep_original_field_names = false
+
+  ## The time that a series is not updated until considering it final. Ignored
+  ## when output_strategy is "periodic".
+  # series_timeout = "5m"
+
+  ## Output strategy, supported values:
+  ##   timeout  -- output a metric if no new input arrived for `series_timeout`
+  ##   periodic -- output the last received metric every `period`
+  # output_strategy = "timeout"
+```
+
+### Output strategy
+
+By default (`output_strategy = "timeout"`) the plugin will only emit a metric
+for the period if the last received one is older than the series_timeout. This
+will not guarantee a regular output of a `final` metric e.g. if the
+series-timeout is a multiple of the gathering interval for an input. In this
+case metric sporadically arrive in the timeout phase of the period and emitting
+the `final` metric is suppressed.
+
+Contrary to this, `output_strategy = "periodic"` will always output a `final`
+metric at the end of the period irrespectively of when the last metric arrived,
+the `series_timeout` is ignored.
+
+## Metrics
+
+Measurement and tags are unchanged, fields are emitted with the suffix
+`_final`.
+
+## Example Output
+
+```text
+counter,host=bar i_final=3,j_final=6 1554281635115090133
+counter,host=foo i_final=3,j_final=6 1554281635112992012
+```
+
+Original input:
+
+```text
+counter,host=bar i=1,j=4 1554281633101153300
+counter,host=foo i=1,j=4 1554281633099323601
+counter,host=bar i=2,j=5 1554281634107980073
+counter,host=foo i=2,j=5 1554281634105931116
+counter,host=bar i=3,j=6 1554281635115090133
+counter,host=foo i=3,j=6 1554281635112992012
+```