| 1 | # Time series selector |
| 2 | |
| 3 | Selectors allow selecting and filtering of a set of time series. |
| 4 | |
| 5 | ## Simple Selector |
| 6 | |
| 7 | In the simplest form you need to specify only a metric name. |
| 8 | |
| 9 | ### Syntax |
| 10 | |
| 11 | ```cmd |
| 12 | <line> ::= <metric_name_pattern> |
| 13 | <metric_name_pattern> ::= simple pattern |
| 14 | ``` |
| 15 | |
| 16 | The metric name pattern syntax is [simple pattern](/src/libnetdata/simple_pattern/README.md). |
| 17 | |
| 18 | ### Examples |
| 19 | |
| 20 | This example selects all time series that have the `go_memstats_alloc_bytes` metric name: |
| 21 | |
| 22 | ```cmd |
| 23 | go_memstats_alloc_bytes |
| 24 | ``` |
| 25 | |
| 26 | This example selects all time series with metric names starts with `go_memstats_`: |
| 27 | |
| 28 | ```cmd |
| 29 | go_memstats_* |
| 30 | ``` |
| 31 | |
| 32 | This example selects all time series with metric names starts with `go_` except `go_memstats_`: |
| 33 | |
| 34 | ```cmd |
| 35 | !go_memstats_* go_* |
| 36 | ``` |
| 37 | |
| 38 | ## Advanced Selector |
| 39 | |
| 40 | It is possible to filter these time series further by appending a comma separated list of label matchers in curly braces (`{}`). |
| 41 | |
| 42 | ### Syntax |
| 43 | |
| 44 | ```cmd |
| 45 | <line> ::= [ <metric_name_pattern> ]{ <list_of_selectors> } |
| 46 | <metric_name_pattern> ::= simple pattern |
| 47 | <list_of_selectors> ::= a comma separated list <label_name><op><label_value_pattern> |
| 48 | <label_name> ::= an exact label name |
| 49 | <op> ::= [ '=', '!=', '=~', '!~', '=*', '!*' ] |
| 50 | <label_value_pattern> ::= a label value pattern, depends on <op> |
| 51 | ``` |
| 52 | |
| 53 | The metric name pattern syntax is [simple pattern](/src/libnetdata/simple_pattern/README.md). |
| 54 | |
| 55 | Label matching operators: |
| 56 | |
| 57 | - `=`: Match labels that are exactly equal to the provided string. |
| 58 | - `!=`: Match labels that are not equal to the provided string. |
| 59 | - `=~`: Match labels that [regex-match](https://golang.org/pkg/regexp/syntax/) the provided string. |
| 60 | - `!~`: Match labels that do not [regex-match](https://golang.org/pkg/regexp/syntax/) the provided string. |
| 61 | - `=*`: Match labels that [simple-pattern-match](/src/libnetdata/simple_pattern/README.md) the provided string. |
| 62 | - `!*`: Match labels that do not [simple-pattern-match](/src/libnetdata/simple_pattern/README.md) the provided string. |
| 63 | |
| 64 | ### Examples |
| 65 | |
| 66 | This example selects all time series that: |
| 67 | |
| 68 | - have the `node_cooling_device_cur_state` metric name and |
| 69 | - label `type` value not equal to `Fan`: |
| 70 | |
| 71 | ```cmd |
| 72 | node_cooling_device_cur_state{type!="Fan"} |
| 73 | ``` |
| 74 | |
| 75 | This example selects all time series that: |
| 76 | |
| 77 | - have the `node_filesystem_size_bytes` metric name and |
| 78 | - label `device` value is either `/dev/nvme0n1p1` or `/dev/nvme0n1p2` and |
| 79 | - label `fstype` is equal to `ext4` |
| 80 | |
| 81 | ```cmd |
| 82 | node_filesystem_size_bytes{device=~"/dev/nvme0n1p1$|/dev/nvme0n1p2$",fstype="ext4"} |
| 83 | ``` |
| 84 | |
| 85 | Label matchers can also be applied to metric names by matching against the internal `__name__` label. |
| 86 | |
| 87 | For example, the expression `node_filesystem_size_bytes` is equivalent to `{__name__="node_filesystem_size_bytes"}`. |
| 88 | This allows using all operators (other than `=*`) for metric names matching. |
| 89 | |
| 90 | The following expression selects all metrics that have a name starting with `node_`: |
| 91 | |
| 92 | ```cmd |
| 93 | {__name__=*"node_*"} |
| 94 | ``` |