github.com/netdata/go.d.plugin@v0.58.1/pkg/matcher/README.md (about)

     1  <!--
     2  title: "matcher"
     3  custom_edit_url: "https://github.com/netdata/go.d.plugin/edit/master/pkg/matcher/README.md"
     4  sidebar_label: "matcher"
     5  learn_status: "Published"
     6  learn_rel_path: "Developers/External plugins/go.d.plugin/Helper Packages"
     7  -->
     8  
     9  # matcher
    10  ## Supported Format
    11  
    12  * string
    13  * glob
    14  * regexp
    15  * simple patterns
    16  
    17  Depending on the symbol at the start of the string, the `matcher` will use one of the supported formats.
    18  
    19  | matcher         | short format | long format       |
    20  |-----------------|--------------|-------------------|
    21  | string          | ` =`         | `string`          |
    22  | glob            | `*`          | `glob`            |
    23  | regexp          | `~`          | `regexp`          |
    24  | simple patterns |              | `simple_patterns` |
    25  
    26  Example:
    27  
    28  - `* pattern`: It will use the `glob` matcher to find the `pattern` in the string.
    29  
    30  ### Syntax
    31  
    32  **Tip**: Read `::=` as `is defined as`.
    33  
    34  ```
    35  Short Syntax
    36       [ <not> ] <format> <space> <expr>
    37       
    38       <not>       ::= '!'
    39                         negative expression
    40       <format>    ::= [ '=', '~', '*' ]
    41                         '=' means string match
    42                         '~' means regexp match
    43                         '*' means glob match
    44       <space>     ::= { ' ' | '\t' | '\n' | '\n' | '\r' }
    45       <expr>      ::= any string
    46  
    47   Long Syntax
    48       [ <not> ] <format> <separator> <expr>
    49       
    50       <format>    ::= [ 'string' | 'glob' | 'regexp' | 'simple_patterns' ]
    51       <not>       ::= '!'
    52                         negative expression
    53       <separator> ::= ':'
    54       <expr>      ::= any string
    55  ```
    56  
    57  When using the short syntax, you can enable the glob format by starting the string with a `*`, while in the long syntax
    58  you need to define it more explicitly. The following examples are identical. `simple_patterns` can be used **only** with
    59  the long syntax.
    60  
    61  Examples:
    62  
    63  - Short Syntax: `'* * '`
    64  - Long Syntax: `'glob:*'`
    65  
    66  ### String matcher
    67  
    68  The string matcher reports whether the given value equals to the string.
    69  
    70  Examples:
    71  
    72  - `'= foo'` matches only if the string is `foo`.
    73  - `'!= bar'` matches any string that is not `bar`.
    74  
    75  String matcher means **exact match** of the `string`. There are other string match related cases:
    76  
    77  - string has prefix `something`
    78  - string has suffix `something`
    79  - string contains `something`
    80  
    81  This is achievable using the `glob` matcher:
    82  
    83  - `* PREFIX*`, means that it matches with any string that *starts* with `PREFIX`, e.g `PREFIXnetdata`
    84  - `* *SUFFIX`, means that it matches with any string that *ends* with `SUFFIX`, e.g `netdataSUFFIX`
    85  - `* *SUBSTRING*`, means that it matches with any string that *contains* `SUBSTRING`, e.g `netdataSUBSTRINGnetdata`
    86  
    87  ### Glob matcher
    88  
    89  The glob matcher reports whether the given value matches the wildcard pattern. It uses the standard `golang`
    90  library `path`. You can read more about the library in the [golang documentation](https://golang.org/pkg/path/#Match),
    91  where you can also practice with the library in order to learn the syntax and use it in your Netdata configuration.
    92  
    93  The pattern syntax is:
    94  
    95  ```
    96      pattern:
    97          { term }
    98      term:
    99          '*'         matches any sequence of characters
   100          '?'         matches any single character
   101          '[' [ '^' ] { character-range } ']'
   102          character class (must be non-empty)
   103          c           matches character c (c != '*', '?', '\\', '[')
   104          '\\' c      matches character c
   105  
   106      character-range:
   107          c           matches character c (c != '\\', '-', ']')
   108          '\\' c      matches character c
   109          lo '-' hi   matches character c for lo <= c <= hi
   110  ```
   111  
   112  Examples:
   113  
   114  - `* ?` matches any string that is a single character.
   115  - `'?a'` matches any 2 character string that starts with any character and the second character is `a`, like `ba` but
   116    not `bb` or `bba`.
   117  - `'[^abc]'` matches any character that is NOT a,b,c. `'[abc]'` matches only a, b, c.
   118  - `'*[a-d]'` matches any string (`*`) that ends with a character that is between `a` and `d` (i.e `a,b,c,d`).
   119  
   120  ### Regexp matcher
   121  
   122  The regexp matcher reports whether the given value matches the RegExp pattern ( use regexp.Match ).
   123  
   124  The RegExp syntax is described at https://golang.org/pkg/regexp/syntax/.
   125  
   126  Learn more about regular expressions at [RegexOne](https://regexone.com/).
   127  
   128  ### Simple patterns matcher
   129  
   130  The simple patterns matcher reports whether the given value matches the simple patterns.
   131  
   132  Simple patterns are a space separated list of words. Each word may use any number of wildcards `*`. Simple patterns
   133  allow negative matches by prefixing a word with `!`.
   134  
   135  Examples:
   136  
   137  - `!*bad* *` matches anything, except all those that contain the word bad.
   138  - `*foobar* !foo* !*bar *` matches everything containing foobar, except strings that start with foo or end with bar.
   139  
   140  
   141  
   142