Skip to content

Commit e45f856

Browse files
committed
Added a Using UTF-8 section to demonstrate a few examples on how to utilize UTF-8 support
Signed-off-by: Raphael Skuza <rapsku.dev@gmail.com>
1 parent 308fad2 commit e45f856

1 file changed

Lines changed: 64 additions & 0 deletions

File tree

docs/guides/utf8-support.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,70 @@ YAML:
5050
name_validation_scheme: utf8
5151
```
5252
53+
## Using UTF-8
54+
55+
After enabling UTF-8 name validation, UTF-8 metric names and label names can be used. The examples below show practical examples.
56+
57+
### Querying
58+
59+
PromQL queries support UTF-8 metric names and label names. For example, a UTF-8 metric name can be queried with the following expression:
60+
61+
```promql
62+
series.1{"test.utf8.metric"="😄"}
63+
```
64+
65+
Note, that the metric name `series.1` is not valid under the `legacy` validation scheme. It is accepted only when UTF-8 validation is enabled. This is useful when metric or label names contain characters, such as `.`, that are supported by UTF-8 validation but not by the legacy validation scheme.
66+
67+
### Alertmanager
68+
69+
Alertmanager configuration can use UTF-8 names in matchers, `group_by` fields, and silence matchers. For example, a route can group and match on UTF-8 label names:
70+
71+
```yaml
72+
route:
73+
receiver: default
74+
group_by:
75+
- "group.test.🙂"
76+
routes:
77+
- receiver: utf8-receiver
78+
matchers:
79+
- '"🙂.utf8.label"="😄"'
80+
81+
receivers:
82+
- name: default
83+
- name: utf8-receiver
84+
```
85+
86+
Silences can also match alerts using UTF-8 label names and values. For example:
87+
88+
```yaml
89+
matchers:
90+
- "🙂.utf8.label"
91+
value: "😄"
92+
isRegex: false
93+
```
94+
95+
This allows alert routing, silencing and grouping to work with alerts that contain UTF-8 label names and values.
96+
97+
### Ruler
98+
99+
Ruler rule definition can use UTF-8 names in rule names, rule labels and rule group labels. For example:
100+
101+
```yaml
102+
groups:
103+
- name: "test.utf8.group"
104+
labels:
105+
"test.utf8.group.label": "😄"
106+
rules:
107+
- record: "test.utf8.recording.rule"
108+
expr: up
109+
labels:
110+
"test.utf8.rule.label": "😄"
111+
- alert: "test.utf8.alert"
112+
expr: up == 0
113+
labels:
114+
"test.utf8.alert.label": "😄"
115+
```
116+
53117
## Impact on Cortex components
54118
55119
### Distributor

0 commit comments

Comments
 (0)