Skip to content

docs: clarify YAML quoting vs matcher token quoting #5264

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Cloud-Architect-Emma wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: clarify YAML quoting vs matcher token quoting #5264

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -633,6 +633,29 @@ Unquoted literals can contain all UTF-8 characters other than the reserved chara

Double-quoted strings can contain all UTF-8 characters. Unlike unquoted literals, there are no reserved characters. However, literal double quotes and backslashes must be escaped with a single backslash. For example, to match the regular expression `\d+` the backslash must be escaped `"\\d+"`. This is because double-quoted strings follow the same rules as Go's [string literals](https://go.dev/ref/spec#String_literals). Double-quoted strings also support UTF-8 code points. For example, `"foo!"`, `"bar,baz"`, `"\"baz qux\""` and `"\xf0\x9f\x99\x82"`.


> **Note: YAML quoting vs. matcher token quoting**
>
> Each entry in a `matchers:` list is a single YAML value. YAML quoting applies
> to the *entire* matcher string — it does not parse or protect individual tokens
> within it. The double-quoting described above is handled by Alertmanager's own
> parser after YAML has already processed the input.
>
> - **Plain style** (no surrounding quotes): works when the matcher contains no
> YAML special characters (`{`, `}`, `[`, `]`, `,`, `#`, `|`, `>`, `:`).
> Example: `env !~ preprod`
> - **Single-quoted style** (recommended): protects against all YAML special
> characters and allows literal double quotes inside the matcher.
> Example: `'env =~ "prod|staging"'`
> - **Double-quoted style**: supports YAML escape sequences; literal double quotes
> inside the value must be escaped as `\"`.
> Example: `"env !~ \"uat\""`
>
> Writing `env =~ "prod"` without surrounding YAML quotes is valid plain-style
> YAML. The inner double quotes are stripped by Alertmanager's parser and provide
> **no** protection against YAML special characters. Always quote the entire
> matcher at the YAML level when the value may contain special characters.

#### Classic matchers

A classic matcher is a string with a syntax inspired by PromQL and OpenMetrics. The syntax of a classic matcher consists of three tokens:
Expand Down