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