Processor & Aggregator configuration doccing

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"]
+```