dom
/
telegraf
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Processor & Aggregator configuration doccing

This commit is contained in:
Cameron Sparr 2016-10-05 13:53:43 +01:00
parent 78f544c0aa
commit acfdd15aa9
3 changed files with 133 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
README.md
View File

@ -86,42 +86,43 @@ if you don't have it already. You also must build with golang version 1.5+.
## How to use it: ## How to use it:
```console ```console
$ telegraf -help $ telegraf --help
Telegraf, The plugin-driven server agent for collecting and reporting metrics. Telegraf, The plugin-driven server agent for collecting and reporting metrics.
Usage: Usage:
telegraf <flags> telegraf [commands|flags]
The flags are: The commands & flags are:
-config <file> configuration file to load config print out full sample configuration to stdout
-test gather metrics once, print them to stdout, and exit version print the version to stdout
-sample-config print out full sample configuration to stdout
-config-directory directory containing additional *.conf files --config <file> configuration file to load
-input-filter filter the input plugins to enable, separator is : --test gather metrics once, print them to stdout, and exit
-output-filter filter the output plugins to enable, separator is : --config-directory directory containing additional *.conf files
-usage print usage for a plugin, ie, 'telegraf -usage mysql' --input-filter filter the input plugins to enable, separator is :
-debug print metrics as they're generated to stdout --output-filter filter the output plugins to enable, separator is :
-quiet run in quiet mode --usage print usage for a plugin, ie, 'telegraf -usage mysql'
-version print the version to stdout --debug print metrics as they're generated to stdout
--quiet run in quiet mode
Examples: Examples:
# generate a telegraf config file: # generate a telegraf config file:
telegraf -sample-config > telegraf.conf telegraf config > telegraf.conf
# generate config with only cpu input & influxdb output plugins defined # generate config with only cpu input & influxdb output plugins defined
telegraf -sample-config -input-filter cpu -output-filter influxdb telegraf config -input-filter cpu -output-filter influxdb
# run a single telegraf collection, outputing metrics to stdout # run a single telegraf collection, outputing metrics to stdout
telegraf -config telegraf.conf -test telegraf --config telegraf.conf -test
# run telegraf with all plugins defined in config file # run telegraf with all plugins defined in config file
telegraf -config telegraf.conf telegraf --config telegraf.conf
# run telegraf, enabling the cpu & memory input, and influxdb output plugins # run telegraf, enabling the cpu & memory input, and influxdb output plugins
telegraf -config telegraf.conf -input-filter cpu:mem -output-filter influxdb telegraf --config telegraf.conf -input-filter cpu:mem -output-filter influxdb
``` ```
## Configuration ## Configuration

45
cmd/telegraf/telegraf.go
View File

@ -73,47 +73,38 @@ const usage = `Telegraf, The plugin-driven server agent for collecting and repor
Usage: Usage:
telegraf <flags> telegraf [commands|flags]
The flags are: The commands & flags are:
-config <file> configuration file to load config print out full sample configuration to stdout
-test gather metrics once, print them to stdout, and exit version print the version to stdout
-sample-config print out full sample configuration to stdout
-config-directory directory containing additional *.conf files
-input-filter filter the input plugins to enable, separator is :
-output-filter filter the output plugins to enable, separator is :
-aggregator-filter filter the aggregator plugins to enable, separator is :
-processor-filter filter the processor plugins to enable, separator is :
-usage print usage for a plugin, ie, 'telegraf -usage mysql'
-debug print metrics as they're generated to stdout
-quiet run in quiet mode
-version print the version to stdout
-service Control the service, ie, 'telegraf -service install (windows only)'
In addition to the -config flag, telegraf will also load the config file from --config <file> configuration file to load
an environment variable or default location. Precedence is: --test gather metrics once, print them to stdout, and exit
1. -config flag --config-directory directory containing additional *.conf files
2. $TELEGRAF_CONFIG_PATH environment variable --input-filter filter the input plugins to enable, separator is :
3. $HOME/.telegraf/telegraf.conf --output-filter filter the output plugins to enable, separator is :
4. /etc/telegraf/telegraf.conf --usage print usage for a plugin, ie, 'telegraf --usage mysql'
--debug print metrics as they're generated to stdout
--quiet run in quiet mode
Examples: Examples:
# generate a telegraf config file: # generate a telegraf config file:
telegraf -sample-config > telegraf.conf telegraf config > telegraf.conf
# generate config with only cpu input & influxdb output plugins defined # generate config with only cpu input & influxdb output plugins defined
telegraf -sample-config -input-filter cpu -output-filter influxdb telegraf config -input-filter cpu -output-filter influxdb
# run a single telegraf collection, outputing metrics to stdout # run a single telegraf collection, outputing metrics to stdout
telegraf -config telegraf.conf -test telegraf --config telegraf.conf -test
# run telegraf with all plugins defined in config file # run telegraf with all plugins defined in config file
telegraf -config telegraf.conf telegraf --config telegraf.conf
# run telegraf, enabling the cpu & memory input, and influxdb output plugins # run telegraf, enabling the cpu & memory input, and influxdb output plugins
telegraf -config telegraf.conf -input-filter cpu:mem -output-filter influxdb telegraf --config telegraf.conf --input-filter cpu:mem --output-filter influxdb
` `
var stop chan struct{} var stop chan struct{}
@ -133,7 +124,6 @@ func reloadLoop(stop chan struct{}, s service.Service) {
reload <- true reload <- true
for <-reload { for <-reload {
reload <- false reload <- false
flag.Usage = func() { usageExit(0) }
flag.Parse() flag.Parse()
args := flag.Args() args := flag.Args()
@ -316,6 +306,7 @@ func (p *program) Stop(s service.Service) error {
} }
func main() { func main() {
flag.Usage = func() { usageExit(0) }
flag.Parse() flag.Parse()
if runtime.GOOS == "windows" { if runtime.GOOS == "windows" {
svcConfig := &service.Config{ svcConfig := &service.Config{

125
docs/CONFIGURATION.md
View File

@ -1,38 +1,38 @@
# Telegraf Configuration # Telegraf Configuration
You can see the latest config file with all available plugins here:
[telegraf.conf](https://github.com/influxdata/telegraf/blob/master/etc/telegraf.conf)
## Generating a Configuration File ## Generating a Configuration File
A default Telegraf config file can be generated using the -sample-config flag: A default Telegraf config file can be auto-generated by telegraf:
``` ```
telegraf -sample-config > telegraf.conf telegraf config > telegraf.conf
``` ```
To generate a file with specific inputs and outputs, you can use the To generate a file with specific inputs and outputs, you can use the
-input-filter and -output-filter flags: -input-filter and -output-filter flags:
``` ```
telegraf -sample-config -input-filter cpu:mem:net:swap -output-filter influxdb:kafka telegraf config -input-filter cpu:mem:net:swap -output-filter influxdb:kafka
``` ```
You can see the latest config file with all available plugins here:
[telegraf.conf](https://github.com/influxdata/telegraf/blob/master/etc/telegraf.conf)
## Environment Variables ## Environment Variables
Environment variables can be used anywhere in the config file, simply prepend Environment variables can be used anywhere in the config file, simply prepend
them with $. For strings the variable must be within quotes (ie, "$STR_VAR"), them with $. For strings the variable must be within quotes (ie, "$STR_VAR"),
for numbers and booleans they should be plain (ie, $INT_VAR, $BOOL_VAR) for numbers and booleans they should be plain (ie, $INT_VAR, $BOOL_VAR)
## `[global_tags]` Configuration # Global Tags
Global tags can be specified in the `[global_tags]` section of the config file Global tags can be specified in the `[global_tags]` section of the config file
in key="value" format. All metrics being gathered on this host will be tagged in key="value" format. All metrics being gathered on this host will be tagged
with the tags specified here. with the tags specified here.
## `[agent]` Configuration ## Agent Configuration
Telegraf has a few options you can configure under the `agent` section of the Telegraf has a few options you can configure under the `[agent]` section of the
config. config.
* **interval**: Default data collection interval for all inputs * **interval**: Default data collection interval for all inputs
@ -56,13 +56,61 @@ interval. Maximum flush_interval will be flush_interval + flush_jitter
This is primarily to avoid This is primarily to avoid
large write spikes for users running a large number of telegraf instances. large write spikes for users running a large number of telegraf instances.
ie, a jitter of 5s and flush_interval 10s means flushes will happen every 10-15s. ie, a jitter of 5s and flush_interval 10s means flushes will happen every 10-15s.
* **precision**: By default, precision will be set to the same timestamp order
as the collection interval, with the maximum being 1s. Precision will NOT
be used for service inputs, such as logparser and statsd. Valid values are
"ns", "us" (or "µs"), "ms", "s".
* **logfile**: Specify the log file name. The empty string means to log to stdout.
* **debug**: Run telegraf in debug mode. * **debug**: Run telegraf in debug mode.
* **quiet**: Run telegraf in quiet mode. * **quiet**: Run telegraf in quiet mode (error messages only).
* **hostname**: Override default hostname, if empty use os.Hostname(). * **hostname**: Override default hostname, if empty use os.Hostname().
* **omit_hostname**: If true, do no set the "host" tag in the telegraf agent.
## Input Configuration
The following config parameters are available for all inputs:
* **interval**: How often to gather this metric. Normal plugins use a single
global interval, but if one particular input should be run less or more often,
you can configure that here.
* **name_override**: Override the base name of the measurement.
(Default is the name of the input).
* **name_prefix**: Specifies a prefix to attach to the measurement name.
* **name_suffix**: Specifies a suffix to attach to the measurement name.
* **tags**: A map of tags to apply to a specific input's measurements.
## Output Configuration
There are no generic configuration options available for all outputs.
## Aggregator Configuration
The following config parameters are available for all aggregators:
* **period**: The period on which to flush & clear each aggregator.
* **delay**: The delay before each aggregator is flushed. This is to control
how long for aggregators to wait before receiving metrics from input plugins,
in the case that aggregators are flushing and inputs are gathering on the
same interval.
* **drop_original**: If true, the original metric will be dropped by the
aggregator and will not get sent to the output plugins.
* **name_override**: Override the base name of the measurement.
(Default is the name of the input).
* **name_prefix**: Specifies a prefix to attach to the measurement name.
* **name_suffix**: Specifies a suffix to attach to the measurement name.
* **tags**: A map of tags to apply to a specific input's measurements.
## Processor Configuration
The following config parameters are available for all processors:
* **order**: This is the order in which the processor(s) get executed. If this
is not specified then processor execution order will be random.
#### Measurement Filtering #### Measurement Filtering
Filters can be configured per input or output, see below for examples. Filters can be configured per input, output, processor, or aggregator,
see below for examples.
* **namepass**: An array of strings that is used to filter metrics generated by the * **namepass**: An array of strings that is used to filter metrics generated by the
current input. Each string in the array is tested as a glob match against current input. Each string in the array is tested as a glob match against
@ -90,19 +138,6 @@ the tag keys in the final measurement.
the plugin definition, otherwise subsequent plugin config options will be the plugin definition, otherwise subsequent plugin config options will be
interpreted as part of the tagpass/tagdrop map. interpreted as part of the tagpass/tagdrop map.
## Input Configuration
Some configuration options are configurable per input:
* **name_override**: Override the base name of the measurement.
(Default is the name of the input).
* **name_prefix**: Specifies a prefix to attach to the measurement name.
* **name_suffix**: Specifies a suffix to attach to the measurement name.
* **tags**: A map of tags to apply to a specific input's measurements.
* **interval**: How often to gather this metric. Normal plugins use a single
global interval, but if one particular input should be run less or more often,
you can configure that here.
#### Input Configuration Examples #### Input Configuration Examples
This is a full working config that will output CPU data to an InfluxDB instance This is a full working config that will output CPU data to an InfluxDB instance
@ -254,11 +289,7 @@ to avoid measurement collisions:
fielddrop = ["cpu_time*"] fielddrop = ["cpu_time*"]
``` ```
## Output Configuration #### Output Configuration Examples:
Telegraf also supports specifying multiple output sinks to send data to,
configuring each output sink is different, but examples can be
found by running `telegraf -sample-config`.
```toml ```toml
[[outputs.influxdb]] [[outputs.influxdb]]
@ -283,3 +314,39 @@ found by running `telegraf -sample-config`.
[outputs.influxdb.tagpass] [outputs.influxdb.tagpass]
cpu = ["cpu0"] cpu = ["cpu0"]
``` ```
#### Aggregator Configuration Examples:
This will collect and emit the min/max of the system load1 metric every
30s, dropping the originals.
```toml
[[inputs.system]]
fieldpass = ["load1"] # collects system load1 metric.
[[aggregators.minmax]]
period = "30s" # send & clear the aggregate every 30s.
drop_original = true # drop the original metrics.
[[outputs.file]]
files = ["stdout"]
```
This will collect and emit the min/max of the swap metrics every
30s, dropping the originals. The aggregator will not be applied
to the system load metrics due to the `namepass` parameter.
```toml
[[inputs.swap]]
[[inputs.system]]
fieldpass = ["load1"] # collects system load1 metric.
[[aggregators.minmax]]
period = "30s" # send & clear the aggregate every 30s.
drop_original = true # drop the original metrics.
namepass = ["swap"] # only "pass" swap metrics through the aggregator.
[[outputs.file]]
files = ["stdout"]
```