Update filtering documentation (#2631)

docs/CONFIGURATION.md

@@ -124,31 +124,40 @@ is not specified then processor execution order will be random.
 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**:
-current input. Each string in the array is tested as a glob match against
+An array of glob pattern strings.  Only points whose measurement name matches
-measurement names and if it matches, the field is emitted.
+a pattern in this list are emitted.
-* **namedrop**: The inverse of pass, if a measurement name matches, it is not emitted.
+* **namedrop**:
-* **fieldpass**: An array of strings that is used to filter metrics generated by the
+The inverse of `namepass`.  If a match is found the point is discarded. This
-current input. Each string in the array is tested as a glob match against field names
+is tested on points after they have passed the `namepass` test.
-and if it matches, the field is emitted. fieldpass is not available for outputs.
+* **fieldpass**:
-* **fielddrop**: The inverse of pass, if a field name matches, it is not emitted.
+An array of glob pattern strings.  Only fields whose field key matches a
-fielddrop is not available for outputs.
+pattern in this list are emitted.  Not available for outputs.
-* **tagpass**: tag names and arrays of strings that are used to filter
+* **fielddrop**:
-measurements by the current input. Each string in the array is tested as a glob
+The inverse of `fieldpass`. Fields with a field key matching one of the
-match against the tag name, and if it matches the measurement is emitted.
+patterns will be discarded from the point.  Not available for outputs.
-* **tagdrop**: The inverse of tagpass. If a tag matches, the measurement is not
+* **tagpass**:
-emitted. This is tested on measurements that have passed the tagpass test.
+A table mapping tag keys to arrays of glob pattern strings.  Only points
-* **tagexclude**: tagexclude can be used to exclude a tag from measurement(s).
+that contain a tag key in the table and a tag value matching one of its
-As opposed to tagdrop, which will drop an entire measurement based on it's
+patterns is emitted.
-tags, tagexclude simply strips the given tag keys from the measurement. This
+* **tagdrop**:
-can be used on inputs & outputs, but it is _recommended_ to be used on inputs,
+The inverse of `tagpass`.  If a match is found the point is discarded. This
-as it is more efficient to filter out tags at the ingestion point.
+is tested on points after they have passed the `tagpass` test.
-* **taginclude**: taginclude is the inverse of tagexclude. It will only include
+* **taginclude**:
-the tag keys in the final measurement.
+An array of glob pattern strings.  Only tags with a tag key matching one of
+the patterns are emitted.  In contrast to `tagpass`, which will pass an entire
+point based on its tag, `taginclude` removes all non matching tags from the
+point.  This filter can be used on both inputs & outputs, but it is
+_recommended_ to be used on inputs, as it is more efficient to filter out tags
+at the ingestion point.
+* **tagexclude**:
+The inverse of `taginclude`. Tags with a tag key matching one of the patterns
+will be discarded from the point.
 
-**NOTE** `tagpass` and `tagdrop` parameters must be defined at the _end_ of
+**NOTE** Due to the way TOML is parsed, `tagpass` and `tagdrop` parameters
-the plugin definition, otherwise subsequent plugin config options will be
+must be defined at the _end_ of the plugin definition, otherwise subsequent
-interpreted as part of the tagpass/tagdrop map.
+plugin config options will be interpreted as part of the tagpass/tagdrop
+tables.
 
 #### Input Configuration Examples