Skip to content

Commit 0335be3

Browse files
jstirnamanjstirnaman
authored
Merge branch 'master' into jts/fix-telegraf-aggregator-typo-intro
2 parents 9e3c5ba + da65919 commit 0335be3

File tree

352 files changed

+59635
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

352 files changed

+59635
-0
lines changed

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

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: "Telegraf Aggregator Plugins"
3+
description: "Telegraf aggregator plugins aggregate data across multiple metrics."
4+
menu:
5+
telegraf_v1_ref:
6+
name: Aggregator plugins
7+
parent: plugins_reference
8+
identifier: aggregator_plugins_reference
9+
weight: 10
10+
tags: [aggregator-plugins]
11+
---
12+
13+
Telegraf aggregator plugins aggregate data across multiple metrics.
14+
Aggregator plugins create aggregate metrics--for example, by implementing statistical functions such as mean, min, and max.
15+
16+
{{< telegraf/plugins type="aggregator" >}}

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

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
description: "Telegraf plugin for aggregating metrics using Basic Statistics"
3+
menu:
4+
telegraf_v1_ref:
5+
parent: aggregator_plugins_reference
6+
name: Basic Statistics
7+
identifier: aggregator-basicstats
8+
tags: [Basic Statistics, "aggregator-plugins", "configuration", "statistics"]
9+
introduced: "v1.5.0"
10+
os_support: "freebsd, linux, macos, solaris, windows"
11+
related:
12+
- /telegraf/v1/configure_plugins/
13+
- https://github.com/influxdata/telegraf/tree/v1.36.1/plugins/aggregators/basicstats/README.md, Basic Statistics Plugin Source
14+
---
15+
16+
# Basic Statistics Aggregator Plugin
17+
18+
This plugin computes basic statistics such as counts, differences, minima,
19+
maxima, mean values, non-negative differences etc. for a set of metrics and
20+
emits these statistical values every `period`.
21+
22+
**Introduced in:** Telegraf v1.5.0
23+
**Tags:** statistics
24+
**OS support:** all
25+
26+
## Global configuration options <!-- @/docs/includes/plugin_config.md -->
27+
28+
In addition to the plugin-specific configuration settings, plugins support
29+
additional global and plugin configuration settings. These settings are used to
30+
modify metrics, tags, and field or create aliases and configure ordering, etc.
31+
See the [CONFIGURATION.md](/telegraf/v1/configuration/#plugins) for more details.
32+
33+
[CONFIGURATION.md]: ../../../docs/CONFIGURATION.md#plugins
34+
35+
## Configuration
36+
37+
```toml @sample.conf
38+
# Keep the aggregate basicstats of each metric passing through.
39+
[[aggregators.basicstats]]
40+
## The period on which to flush & clear the aggregator.
41+
# period = "30s"
42+
43+
## If true, the original metric will be dropped by the
44+
## aggregator and will not get sent to the output plugins.
45+
# drop_original = false
46+
47+
## Configures which basic stats to push as fields
48+
# stats = ["count","min","max","mean","variance","stdev"]
49+
```
50+
51+
- stats
52+
- If not specified, then `count`, `min`, `max`, `mean`, `stdev`, and `s2` are
53+
aggregated and pushed as fields. Other fields are not aggregated by default
54+
to maintain backwards compatibility.
55+
- If empty array, no stats are aggregated
56+
57+
## Measurements & Fields
58+
59+
- measurement1
60+
- field1_count
61+
- field1_diff (difference)
62+
- field1_rate (rate per second)
63+
- field1_max
64+
- field1_min
65+
- field1_mean
66+
- field1_non_negative_diff (non-negative difference)
67+
- field1_non_negative_rate (non-negative rate per second)
68+
- field1_percent_change
69+
- field1_sum
70+
- field1_s2 (variance)
71+
- field1_stdev (standard deviation)
72+
- field1_interval (interval in nanoseconds)
73+
- field1_last (last aggregated value)
74+
- field1_first (first aggregated value)
75+
76+
## Tags
77+
78+
No tags are applied by this aggregator.
79+
80+
## Example Output
81+
82+
```text
83+
system,host=tars load1=1 1475583980000000000
84+
system,host=tars load1=1 1475583990000000000
85+
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
86+
system,host=tars load1=1 1475584020000000000
87+
system,host=tars load1=3 1475584030000000000
88+
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
89+
```

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

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
description: "Telegraf plugin for aggregating metrics using Derivative"
3+
menu:
4+
telegraf_v1_ref:
5+
parent: aggregator_plugins_reference
6+
name: Derivative
7+
identifier: aggregator-derivative
8+
tags: [Derivative, "aggregator-plugins", "configuration", "math"]
9+
introduced: "v1.18.0"
10+
os_support: "freebsd, linux, macos, solaris, windows"
11+
related:
12+
- /telegraf/v1/configure_plugins/
13+
- https://github.com/influxdata/telegraf/tree/v1.36.1/plugins/aggregators/derivative/README.md, Derivative Plugin Source
14+
---
15+
16+
# Derivative Aggregator Plugin
17+
18+
This plugin computes the derivative for all fields of the aggregated metrics.
19+
20+
**Introduced in:** Telegraf v1.18.0
21+
**Tags:** math
22+
**OS support:** all
23+
24+
## Global configuration options <!-- @/docs/includes/plugin_config.md -->
25+
26+
In addition to the plugin-specific configuration settings, plugins support
27+
additional global and plugin configuration settings. These settings are used to
28+
modify metrics, tags, and field or create aliases and configure ordering, etc.
29+
See the [CONFIGURATION.md](/telegraf/v1/configuration/#plugins) for more details.
30+
31+
[CONFIGURATION.md]: ../../../docs/CONFIGURATION.md#plugins
32+
33+
## Configuration
34+
35+
```toml @sample.conf
36+
# Calculates a derivative for every field.
37+
[[aggregators.derivative]]
38+
## The period in which to flush the aggregator.
39+
# period = "30s"
40+
41+
## Suffix to append for the resulting derivative field.
42+
# suffix = "_rate"
43+
44+
## Field to use for the quotient when computing the derivative.
45+
## When using a field as the derivation parameter the name of that field will
46+
## be used for the resulting derivative, e.g. *fieldname_by_parameter*.
47+
## By default the timestamps of the metrics are used and the suffix is omitted.
48+
# variable = ""
49+
50+
## Maximum number of roll-overs in case only one measurement is found during a period.
51+
# max_roll_over = 10
52+
```
53+
54+
This aggregator will estimate a derivative for each field of a metric, which is
55+
contained in both the first and last metric of the aggregation interval.
56+
Without further configuration the derivative will be calculated with respect to
57+
the time difference between these two measurements in seconds.
58+
The following formula is applied is for every field
59+
60+
```text
61+
derivative = (value_last - value_first) / (time_last - time_first)
62+
```
63+
64+
The resulting derivative will be named `<fieldname>_rate` if no `suffix` is
65+
configured.
66+
67+
To calculate a derivative for every field use
68+
69+
```toml
70+
[[aggregators.derivative]]
71+
## Specific Derivative Aggregator Arguments:
72+
73+
## Configure a custom derivation variable. Timestamp is used if none is given.
74+
# variable = ""
75+
76+
## Suffix to add to the field name for the derivative name.
77+
# suffix = "_rate"
78+
79+
## Roll-Over last measurement to first measurement of next period
80+
# max_roll_over = 10
81+
82+
## General Aggregator Arguments:
83+
84+
## calculate derivative every 30 seconds
85+
period = "30s"
86+
```
87+
88+
## Time Derivatives
89+
90+
In its default configuration it determines the first and last measurement of
91+
the period. From these measurements the time difference in seconds is
92+
calculated. This time difference is than used to divide the difference of each
93+
field using the following formula:
94+
95+
```text
96+
derivative = (value_last - value_first) / (time_last - time_first)
97+
```
98+
99+
For each field the derivative is emitted with a naming pattern
100+
`<fieldname>_rate`.
101+
102+
## Custom Derivation Variable
103+
104+
The plugin supports to use a field of the aggregated measurements as derivation
105+
variable in the denominator. This variable is assumed to be a monotonically
106+
increasing value. In this feature the following formula is used:
107+
108+
```text
109+
derivative = (value_last - value_first) / (variable_last - variable_first)
110+
```
111+
112+
**Make sure the specified variable is not filtered and exists in the metrics
113+
passed to this aggregator!**
114+
115+
When using a custom derivation variable, you should change the `suffix` of the
116+
derivative name. See the next section on customizing the derivative
117+
name |
118+
| 16 | 4.0 | | | | |
119+
| 18 | 2.0 | | | | |
120+
| 20 | 0.0 | | | | |
121+
||| -1.0 | -1.0 | | |
122+
123+
The difference stems from the change of the value between periods, e.g. from 6.0
124+
to 8.0 between first and second period. Those changes are omitted with
125+
`max_roll_over = 0` but are respected with `max_roll_over = 1`. That there are
126+
no more differences in the calculated derivatives is due to the example data,
127+
which has constant derivatives in during the first and last period, even when
128+
including the gap between the periods. Using `max_roll_over` with a value
129+
greater 0 may be important, if you need to detect changes between periods,
130+
e.g. when you have very few measurements in a period or quasi-constant metrics
131+
with only occasional changes.
132+
133+
### Tags
134+
135+
No tags are applied by this aggregator.
136+
Existing tags are passed through the aggregator untouched.
137+
138+
## Example Output
139+
140+
```text
141+
net bytes_recv=15409i,packets_recv=164i,bytes_sent=16649i,packets_sent=120i 1508843640000000000
142+
net bytes_recv=73987i,packets_recv=364i,bytes_sent=87328i,packets_sent=452i 1508843660000000000
143+
net bytes_recv_by_packets_recv=292.89 1508843660000000000
144+
net packets_sent_rate=16.6,bytes_sent_rate=3533.95 1508843660000000000
145+
net bytes_sent_by_packet=292.89 1508843660000000000
146+
```

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

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
---
2+
description: "Telegraf plugin for aggregating metrics using Final"
3+
menu:
4+
telegraf_v1_ref:
5+
parent: aggregator_plugins_reference
6+
name: Final
7+
identifier: aggregator-final
8+
tags: [Final, "aggregator-plugins", "configuration", "sampling"]
9+
introduced: "v1.11.0"
10+
os_support: "freebsd, linux, macos, solaris, windows"
11+
related:
12+
- /telegraf/v1/configure_plugins/
13+
- https://github.com/influxdata/telegraf/tree/v1.36.1/plugins/aggregators/final/README.md, Final Plugin Source
14+
---
15+
16+
# Final Aggregator Plugin
17+
18+
This plugin emits the last metric of a contiguous series, defined as a
19+
series which receives updates within the time period in `series_timeout`. The
20+
contiguous series may be longer than the time interval defined by `period`.
21+
When a series has not been updated within the `series_timeout`, the last metric
22+
is emitted.
23+
24+
Alternatively, the plugin emits the last metric in the `period` for the
25+
`periodic` output strategy.
26+
27+
This is useful for getting the final value for data sources that produce
28+
discrete time series such as procstat, cgroup, kubernetes etc. or to downsample
29+
metrics collected at a higher frequency.
30+
31+
> [!NOTE]
32+
> All emited metrics do have fields with `_final` appended to the field-name
33+
> by default.
34+
35+
**Introduced in:** Telegraf v1.11.0
36+
**Tags:** sampling
37+
**OS support:** all
38+
39+
## Global configuration options <!-- @/docs/includes/plugin_config.md -->
40+
41+
In addition to the plugin-specific configuration settings, plugins support
42+
additional global and plugin configuration settings. These settings are used to
43+
modify metrics, tags, and field or create aliases and configure ordering, etc.
44+
See the [CONFIGURATION.md](/telegraf/v1/configuration/#plugins) for more details.
45+
46+
[CONFIGURATION.md]: ../../../docs/CONFIGURATION.md#plugins
47+
48+
## Configuration
49+
50+
```toml @sample.conf
51+
# Report the final metric of a series
52+
[[aggregators.final]]
53+
## The period on which to flush & clear the aggregator.
54+
# period = "30s"
55+
56+
## If true, the original metric will be dropped by the
57+
## aggregator and will not get sent to the output plugins.
58+
# drop_original = false
59+
60+
## If false, _final is added to every field name
61+
# keep_original_field_names = false
62+
63+
## The time that a series is not updated until considering it final. Ignored
64+
## when output_strategy is "periodic".
65+
# series_timeout = "5m"
66+
67+
## Output strategy, supported values:
68+
## timeout -- output a metric if no new input arrived for `series_timeout`
69+
## periodic -- output the last received metric every `period`
70+
# output_strategy = "timeout"
71+
```
72+
73+
### Output strategy
74+
75+
By default (`output_strategy = "timeout"`) the plugin will only emit a metric
76+
for the period if the last received one is older than the series_timeout. This
77+
will not guarantee a regular output of a `final` metric e.g. if the
78+
series-timeout is a multiple of the gathering interval for an input. In this
79+
case metric sporadically arrive in the timeout phase of the period and emitting
80+
the `final` metric is suppressed.
81+
82+
Contrary to this, `output_strategy = "periodic"` will always output a `final`
83+
metric at the end of the period irrespectively of when the last metric arrived,
84+
the `series_timeout` is ignored.
85+
86+
## Metrics
87+
88+
Measurement and tags are unchanged, fields are emitted with the suffix
89+
`_final`.
90+
91+
## Example Output
92+
93+
```text
94+
counter,host=bar i_final=3,j_final=6 1554281635115090133
95+
counter,host=foo i_final=3,j_final=6 1554281635112992012
96+
```
97+
98+
Original input:
99+
100+
```text
101+
counter,host=bar i=1,j=4 1554281633101153300
102+
counter,host=foo i=1,j=4 1554281633099323601
103+
counter,host=bar i=2,j=5 1554281634107980073
104+
counter,host=foo i=2,j=5 1554281634105931116
105+
counter,host=bar i=3,j=6 1554281635115090133
106+
counter,host=foo i=3,j=6 1554281635112992012
107+
```

0 commit comments

Comments
 (0)