Skip to content

docs: document VictorOps custom_fields in configuration #5184

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
must108 wants to merge 4 commits into
base: main
Choose a base branch
from
Open

docs: document VictorOps custom_fields in configuration #5184

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e8f6f80
docs: add victorops custom_fields to configuration reference
must108 Apr 20, 2026
066f551
Resolve code review
must108 May 4, 2026
3e8c713
Merge branch 'main' into docs/victorops-custom-fields
must108 May 4, 2026
ff79f9d
Merge branch 'main' into docs/victorops-custom-fields
must108 May 28, 2026
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
233 changes: 113 additions & 120 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,17 +46,17 @@ value is set to the specified default.

Generic placeholders are defined as follows:

* `<duration>`: a duration matching the regular expression `((([0-9]+)y)?(([0-9]+)w)?(([0-9]+)d)?(([0-9]+)h)?(([0-9]+)m)?(([0-9]+)s)?(([0-9]+)ms)?|0)`, e.g. `1d`, `1h30m`, `5m`, `10s`
* `<labelname>`: a string matching the regular expression `[a-zA-Z_][a-zA-Z0-9_]*`
* `<labelvalue>`: a string of unicode characters
* `<filepath>`: a valid path in the current working directory
* `<boolean>`: a boolean that can take the values `true` or `false`
* `<string>`: a regular string
* `<secret>`: a regular string that is a secret, such as a password
* `<tmpl_string>`: a string which is template-expanded before usage
* `<tmpl_secret>`: a string which is template-expanded before usage that is a secret
* `<int>`: an integer value
* `<regex>`: any valid [RE2 regular expression](https://github.com/google/re2/wiki/Syntax) (The regex is anchored on both ends. To un-anchor the regex, use `.*<regex>.*`.)
- `<duration>`: a duration matching the regular expression `((([0-9]+)y)?(([0-9]+)w)?(([0-9]+)d)?(([0-9]+)h)?(([0-9]+)m)?(([0-9]+)s)?(([0-9]+)ms)?|0)`, e.g. `1d`, `1h30m`, `5m`, `10s`
- `<labelname>`: a string matching the regular expression `[a-zA-Z_][a-zA-Z0-9_]*`
- `<labelvalue>`: a string of unicode characters
- `<filepath>`: a valid path in the current working directory
- `<boolean>`: a boolean that can take the values `true` or `false`
Comment on lines +49 to +53
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add a <bool> alias in the placeholder glossary.

Line 53 defines <boolean>, but the same document frequently uses <bool> (for example, Line 97 and many receiver sections). Defining both in the glossary avoids ambiguity for readers.

✏️ Proposed doc tweak 
 - `<boolean>`: a boolean that can take the values `true` or `false`
+- `<bool>`: alias of `<boolean>`
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- `<duration>`: a duration matching the regular expression `((([0-9]+)y)?(([0-9]+)w)?(([0-9]+)d)?(([0-9]+)h)?(([0-9]+)m)?(([0-9]+)s)?(([0-9]+)ms)?|0)`, e.g. `1d`, `1h30m`, `5m`, `10s`
- `<labelname>`: a string matching the regular expression `[a-zA-Z_][a-zA-Z0-9_]*`
- `<labelvalue>`: a string of unicode characters
- `<filepath>`: a valid path in the current working directory
- `<boolean>`: a boolean that can take the values `true` or `false`
- `<duration>`: a duration matching the regular expression `((([0-9]+)y)?(([0-9]+)w)?(([0-9]+)d)?(([0-9]+)h)?(([0-9]+)m)?(([0-9]+)s)?(([0-9]+)ms)?|0)`, e.g. `1d`, `1h30m`, `5m`, `10s`
- `<labelname>`: a string matching the regular expression `[a-zA-Z_][a-zA-Z0-9_]*`
- `<labelvalue>`: a string of unicode characters
- `<filepath>`: a valid path in the current working directory
- `<boolean>`: a boolean that can take the values `true` or `false`
- `<bool>`: alias of `<boolean>`
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/configuration.md` around lines 49 - 53, Add a glossary alias for <bool>
that mirrors the existing <boolean> definition so readers aren’t confused by the
two forms; update the placeholder list to include `<bool>` with the same
description and regex/values as `<boolean>` (i.e., a boolean that can take the
values `true` or `false`) and ensure any cross-references in the document
(places using `<bool>`) remain accurate; locate the glossary entries around the
existing `<boolean>` and add the `<bool>` line next to it.

- `<string>`: a regular string
- `<secret>`: a regular string that is a secret, such as a password
- `<tmpl_string>`: a string which is template-expanded before usage
- `<tmpl_secret>`: a string which is template-expanded before usage that is a secret
- `<int>`: an integer value
- `<regex>`: any valid [RE2 regular expression](https://github.com/google/re2/wiki/Syntax) (The regex is anchored on both ends. To un-anchor the regex, use `.*<regex>.*`.)

The other placeholders are specified separately.

Expand Down Expand Up @@ -306,47 +306,47 @@ routes:
# The root route with all parameters, which are inherited by the child
# routes if they are not overwritten.
route:
receiver: 'default-receiver'
receiver: "default-receiver"
group_wait: 30s
group_interval: 5m
repeat_interval: 4h
group_by: [cluster, alertname]
# All alerts that do not match the following child routes
# will remain at the root node and be dispatched to 'default-receiver'.
routes:
# All alerts with service=mysql or service=cassandra
# are dispatched to the database pager.
- receiver: 'database-pager'
group_wait: 10s
matchers:
- service=~"mysql|cassandra"
# All alerts with the team=frontend label match this sub-route.
# They are grouped by product and environment rather than cluster
# and alertname.
- receiver: 'frontend-pager'
group_by: [product, environment]
matchers:
- team="frontend"

# All alerts with the service=inhouse-service label match this sub-route.
# the route will be muted during offhours and holidays time intervals.
# even if it matches, it will continue to the next sub-route
- receiver: 'dev-pager'
matchers:
- service="inhouse-service"
mute_time_intervals:
- offhours
- holidays
continue: true

# All alerts with the service=inhouse-service label match this sub-route
# the route will be active only during offhours and holidays time intervals.
- receiver: 'on-call-pager'
matchers:
- service="inhouse-service"
active_time_intervals:
- offhours
- holidays
# All alerts with service=mysql or service=cassandra
# are dispatched to the database pager.
- receiver: "database-pager"
group_wait: 10s
matchers:
- service=~"mysql|cassandra"
# All alerts with the team=frontend label match this sub-route.
# They are grouped by product and environment rather than cluster
# and alertname.
- receiver: "frontend-pager"
group_by: [product, environment]
matchers:
- team="frontend"

# All alerts with the service=inhouse-service label match this sub-route.
# the route will be muted during offhours and holidays time intervals.
# even if it matches, it will continue to the next sub-route
- receiver: "dev-pager"
matchers:
- service="inhouse-service"
mute_time_intervals:
- offhours
- holidays
continue: true

# All alerts with the service=inhouse-service label match this sub-route
# the route will be active only during offhours and holidays time intervals.
- receiver: "on-call-pager"
matchers:
- service="inhouse-service"
active_time_intervals:
- offhours
- holidays
```

### `<time_interval>`
Expand All @@ -356,8 +356,7 @@ in the routing tree to mute/activate particular routes for particular times of t

```yaml
name: <string>
time_intervals:
[ - <time_interval_spec> ... ]
time_intervals: [- <time_interval_spec> ...]
```

#### `<time_interval_spec>`
Expand Down Expand Up @@ -392,8 +391,8 @@ immediately before 24:00. They are specified like so:

```yaml
times:
- start_time: HH:MM
end_time: HH:MM
- start_time: HH:MM
end_time: HH:MM
```

`weekday_range`: A list of days of the week, where the week begins on Sunday and ends on Saturday.
Expand Down Expand Up @@ -422,9 +421,9 @@ contained something like:

```yaml
times:
- start_time: 09:00
end_time: 17:00
weekdays: ['monday:friday']
- start_time: 09:00
end_time: 17:00
weekdays: ["monday:friday"]
```

would include any time that fell between the hours of 9:00AM and 5:00PM, between Monday
Expand Down Expand Up @@ -629,7 +628,7 @@ A UTF-8 matcher consists of three tokens:
- One of `=`, `!=`, `=~`, or `!~`. `=` means equals, `!=` means not equal, `=~` means matches the regular expression and `!~` means doesn't match the regular expression.
- An unquoted literal or a double-quoted string for the regular expression or label value.

Unquoted literals can contain all UTF-8 characters other than the reserved characters. The reserved characters include whitespace and all characters in ``` { } ! = ~ , \ " ' ` ```. For example, `foo`, `[a-zA-Z]+`, and `Προμηθεύς` (Prometheus in Greek) are all examples of valid unquoted literals. However, `foo!` is not a valid literal as `!` is a reserved character.
Unquoted literals can contain all UTF-8 characters other than the reserved characters. The reserved characters include whitespace and all characters in `` { } ! = ~ , \ " ' ` ``. For example, `foo`, `[a-zA-Z]+`, and `Προμηθεύς` (Prometheus in Greek) are all examples of valid unquoted literals. However, `foo!` is not a valid literal as `!` is a reserved character.

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"`.

Expand Down Expand Up @@ -710,37 +709,37 @@ Here are some more examples:

1. Two equals matchers composed as a YAML list:

```yaml
matchers:
- foo = bar
- dings != bums
```
```yaml
matchers:
- foo = bar
- dings != bums
```

2. Two matchers combined composed as a short-form YAML list:

```yaml
matchers: [ foo = bar, dings != bums ]
```
```yaml
matchers: [foo = bar, dings != bums]
```

As shown below, in the short-form, it's better to use double quotes to avoid problems with special characters like commas:

```yaml
matchers: [ "foo = \"bar,baz\"", "dings != bums" ]
matchers: ['foo = "bar,baz"', "dings != bums"]
```

3. You can also put both matchers into one PromQL-like string. Single quotes work best here:

```yaml
matchers: [ '{foo="bar", dings!="bums"}' ]
```
```yaml
matchers: ['{foo="bar", dings!="bums"}']
```

4. To avoid issues with escaping and quoting rules in YAML, you can also use a YAML block:

```yaml
matchers:
- |
{quote=~"She said: \"Hi, all!( How're you…)?\""}
```
```yaml
matchers:
- |
{quote=~"She said: \"Hi, all!( How're you…)?\""}
```

## General receiver-related settings

Expand All @@ -761,45 +760,27 @@ labels:
[ <labelname>: <labelvalue>, ... ]

# Configurations for several notification integrations.
discord_configs:
[ - <discord_config>, ... ]
email_configs:
[ - <email_config>, ... ]
mattermost_configs:
[ - <mattermost_config>, ... ]
msteams_configs:
[ - <msteams_config>, ... ]
msteamsv2_configs:
[ - <msteamsv2_config>, ... ]
jira_configs:
[ - <jira_config>, ... ]
opsgenie_configs:
[ - <opsgenie_config>, ... ]
pagerduty_configs:
[ - <pagerduty_config>, ... ]
incidentio_configs:
[ - <incidentio_config>, ... ]
pushover_configs:
[ - <pushover_config>, ... ]
rocketchat_configs:
[ - <rocketchat_config>, ... ]
slack_configs:
[ - <slack_config>, ... ]
sns_configs:
[ - <sns_config>, ... ]
telegram_configs:
[ - <telegram_config>, ... ]
victorops_configs:
[ - <victorops_config>, ... ]
webex_configs:
[ - <webex_config>, ... ]
webhook_configs:
[ - <webhook_config>, ... ]
wechat_configs:
[ - <wechat_config>, ... ]
```

### `<http_config>` (Shared)
discord_configs: [- <discord_config>, ...]
email_configs: [- <email_config>, ...]
mattermost_configs: [- <mattermost_config>, ...]
msteams_configs: [- <msteams_config>, ...]
msteamsv2_configs: [- <msteamsv2_config>, ...]
jira_configs: [- <jira_config>, ...]
opsgenie_configs: [- <opsgenie_config>, ...]
pagerduty_configs: [- <pagerduty_config>, ...]
incidentio_configs: [- <incidentio_config>, ...]
pushover_configs: [- <pushover_config>, ...]
rocketchat_configs: [- <rocketchat_config>, ...]
slack_configs: [- <slack_config>, ...]
sns_configs: [- <sns_config>, ...]
telegram_configs: [- <telegram_config>, ...]
victorops_configs: [- <victorops_config>, ...]
webex_configs: [- <webex_config>, ...]
webhook_configs: [- <webhook_config>, ...]
wechat_configs: [- <wechat_config>, ...]
```

### `<http_config>` (Shared)

An `http_config` allows configuring the HTTP client that the receiver uses to
communicate with HTTP-based API services.
Expand Down Expand Up @@ -1120,6 +1101,7 @@ webhook_url_file: <filepath>
#### `<attachment_config>`

See [Mattermost documentation](https://developers.mattermost.com/integrate/reference/message-attachments/) for more info.

```yaml
[ fallback: <string> | default = '' ]
[ color: <string> | default = '' ]
Expand All @@ -1143,7 +1125,7 @@ See [Mattermost documentation](https://developers.mattermost.com/integrate/refer

```yaml
# Props card allows for extra information (Markdown-formatted text) to be sent to Mattermost that will only be displayed in the RHS panel after a user selects the info icon displayed alongside the post.
[ card: <string> | default = '' ]
[card: <string> | default = '']
```

#### `<priority_config>`
Expand Down Expand Up @@ -1297,8 +1279,8 @@ The `labels` field is a list of labels added to the issue. Template expressions

```yaml
labels:
- 'alertmanager'
- '{{ .CommonLabels.severity }}'
- "alertmanager"
- "{{ .CommonLabels.severity }}"
```

#### `<jira_field>`
Expand All @@ -1309,14 +1291,15 @@ See https://developer.atlassian.com/server/jira/platform/jira-rest-api-examples/

```yaml
fields:
# Components
components: { name: "Monitoring" }
# Custom Field TextField
customfield_10001: "Random text"
# Custom Field SelectList
customfield_10002: {"value": "red"}
# Custom Field MultiSelect
customfield_10003: [{"value": "red"}, {"value": "blue"}, {"value": "green"}]
# Components
components: { name: "Monitoring" }
# Custom Field TextField
customfield_10001: "Random text"
# Custom Field SelectList
customfield_10002: { "value": "red" }
# Custom Field MultiSelect
customfield_10003:
[{ "value": "red" }, { "value": "blue" }, { "value": "green" }]
```

### `<opsgenie_config>`
Expand Down Expand Up @@ -1856,6 +1839,15 @@ routing_key: <tmpl_string>
# The monitoring tool the state message is from.
[ monitoring_tool: <tmpl_string> | default = '{{ template "victorops.default.monitoring_tool" . }}' ]

# Additional custom fields to include in the request payload.
# Keys must not use names reserved by this integration:
# routing_key, message_type, state_message, entity_display_name,
# monitoring_tool, entity_id, entity_state.
# (Some reserved keys are not part of the JSON body, but are still disallowed
# as custom_fields keys to avoid conflicts with the integrations request/validation.)
Comment on lines +1846 to +1847
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Tighten wording in the VictorOps reserved-key note.

Line 1843 reads a bit awkwardly (“integrations request/validation”). Rephrasing improves clarity in this newly added explanatory note.

✏️ Proposed wording fix 
-# as custom_fields keys to avoid conflicts with the integrations request/validation.)
+# as custom_fields keys to avoid conflicts with the integration's request/validation logic.)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
# (Some reserved keys are not part of the JSON body, but are still disallowed
# as custom_fields keys to avoid conflicts with the integrations request/validation.)
# (Some reserved keys are not part of the JSON body, but are still disallowed
# as custom_fields keys to avoid conflicts with the integration's request/validation logic.)
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/configuration.md` around lines 1842 - 1843, Update the explanatory
parenthetical that begins "Some reserved keys are not part of the JSON body, but
are still disallowed as custom_fields keys to avoid conflicts with the
integrations request/validation." Replace the awkward phrase "integrations
request/validation" with clearer wording such as "integration request and
validation" (so the full sentence reads: "Some reserved keys are not part of the
JSON body, but are still disallowed as custom_fields keys to avoid conflicts
with the integration request and validation.") to improve clarity; target the
line containing "custom_fields" and the parenthetical note.

[ custom_fields:
[ <string>: <tmpl_string> ... ] ]

# The HTTP client's configuration.
[ http_config: <http_config> | default = global.http_config ]
```
Expand Down Expand Up @@ -2021,6 +2013,7 @@ room_id: <tmpl_string>
```

## Tracing Configuration

### `<tracing_config>`

```yaml
Expand Down