From acfdd15aa9ebed3eaca1b892d69eaca164392530 Mon Sep 17 00:00:00 2001 From: Cameron Sparr Date: Wed, 5 Oct 2016 13:53:43 +0100 Subject: [PATCH] Processor & Aggregator configuration doccing --- README.md | 37 ++++++------ cmd/telegraf/telegraf.go | 45 ++++++-------- docs/CONFIGURATION.md | 125 ++++++++++++++++++++++++++++++--------- 3 files changed, 133 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index 737a3fe07..d338caaa9 100644 --- a/README.md +++ b/README.md @@ -86,42 +86,43 @@ if you don't have it already. You also must build with golang version 1.5+. ## How to use it: ```console -$ telegraf -help +$ telegraf --help Telegraf, The plugin-driven server agent for collecting and reporting metrics. Usage: - telegraf + telegraf [commands|flags] -The flags are: +The commands & flags are: - -config configuration file to load - -test gather metrics once, print them to stdout, and exit - -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 : - -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 + config print out full sample configuration to stdout + version print the version to stdout + + --config configuration file to load + --test gather metrics once, print them to stdout, and exit + --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 : + --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: # generate a telegraf config file: - telegraf -sample-config > telegraf.conf + telegraf config > telegraf.conf # 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 - telegraf -config telegraf.conf -test + telegraf --config telegraf.conf -test # 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 - telegraf -config telegraf.conf -input-filter cpu:mem -output-filter influxdb + telegraf --config telegraf.conf -input-filter cpu:mem -output-filter influxdb ``` ## Configuration diff --git a/cmd/telegraf/telegraf.go b/cmd/telegraf/telegraf.go index f57ff385c..620479118 100644 --- a/cmd/telegraf/telegraf.go +++ b/cmd/telegraf/telegraf.go @@ -73,47 +73,38 @@ const usage = `Telegraf, The plugin-driven server agent for collecting and repor Usage: - telegraf + telegraf [commands|flags] -The flags are: +The commands & flags are: - -config configuration file to load - -test gather metrics once, print them to stdout, and exit - -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)' + config print out full sample configuration to stdout + version print the version to stdout -In addition to the -config flag, telegraf will also load the config file from -an environment variable or default location. Precedence is: - 1. -config flag - 2. $TELEGRAF_CONFIG_PATH environment variable - 3. $HOME/.telegraf/telegraf.conf - 4. /etc/telegraf/telegraf.conf + --config configuration file to load + --test gather metrics once, print them to stdout, and exit + --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 : + --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: # generate a telegraf config file: - telegraf -sample-config > telegraf.conf + telegraf config > telegraf.conf # 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 - telegraf -config telegraf.conf -test + telegraf --config telegraf.conf -test # 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 - 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{} @@ -133,7 +124,6 @@ func reloadLoop(stop chan struct{}, s service.Service) { reload <- true for <-reload { reload <- false - flag.Usage = func() { usageExit(0) } flag.Parse() args := flag.Args() @@ -316,6 +306,7 @@ func (p *program) Stop(s service.Service) error { } func main() { + flag.Usage = func() { usageExit(0) } flag.Parse() if runtime.GOOS == "windows" { svcConfig := &service.Config{ diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 46f044ab7..5cf43f532 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -1,38 +1,38 @@ # 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 -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 -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 can be used anywhere in the config file, simply prepend 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) -## `[global_tags]` Configuration +# Global Tags 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 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. * **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 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. +* **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. -* **quiet**: Run telegraf in quiet mode. +* **quiet**: Run telegraf in quiet mode (error messages only). * **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 -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 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 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 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*"] ``` -## Output Configuration - -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`. +#### Output Configuration Examples: ```toml [[outputs.influxdb]] @@ -283,3 +314,39 @@ found by running `telegraf -sample-config`. [outputs.influxdb.tagpass] 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"] +``` \ No newline at end of file