From 6a98f9d8ead8e5a7354f74d6ea7f146638aee4d4 Mon Sep 17 00:00:00 2001 From: Daniel Nelson Date: Thu, 6 Apr 2017 12:06:08 -0700 Subject: [PATCH] Update filtering documentation (#2631) --- docs/CONFIGURATION.md | 57 +++++++++++++++++++++++++------------------ 1 file changed, 33 insertions(+), 24 deletions(-) diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index ff4814b82..ad6e903fc 100644 --- a/docs/CONFIGURATION.md +++ b/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. +* **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** `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. +**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