Repository navigation
[DOC] alertmanager: add plugin documentation - #934
Conversation
Signed-off-by: Joshua (OpenClaw) <s3onghyun@users.noreply.github.com>
Nexucis
left a comment
There was a problem hiding this comment.
Thanks for documenting this plugin, LGTM! I checked the pages against the CUE schemas, the Go SDK and the TS sources, and they match overall; the inline comments are mostly small precisions.
Checked
- The 4 Go SDK examples build and pass
go vet, and every option snippet produces a spec accepted by the CUE schemas. - The
nav.yamlentries point to existing pages.
The comment I'd most like addressed is the one on README.md: the panels can create and expire silences, and allowedActions doesn't restrict who can do that.
Not for this PR
- The Silence Table
durationcolumn sorts its formatted value alphabetically, so10hcomes before2h. - Once the
sortMode: "status"fix mentioned in #933 lands, the Alert TablesortModelist here will needstatustoo.
|
|
||
| The Alertmanager datasource enables connection between Perses and your Alertmanager instance. It works in conjunction with the other plugins from this package, which call the Alertmanager `/api/v2` API through it. Its health check calls the `/api/v2/status` endpoint. | ||
|
|
||
| It supports the [proxy](https://perses.dev/perses/docs/concepts/proxy/) feature of Perses that allows to restrict the access to your data source. |
There was a problem hiding this comment.
Worth spelling out here that these plugins also write to Alertmanager through this datasource: the Alert Table panel and the silences explorer create silences (POST /api/v2/silences), and the Silence Table panel expires them (DELETE /api/v2/silence/{id}).
allowedActions only hides the buttons. Through the proxy, anyone allowed to read the datasource (which viewers of a dashboard using it need anyway) can call these endpoints, and both the proxy config prefilled by the datasource editor and a proxy without allowedEndpoints allow them. A read-only datasource needs only the GET endpoints, for example:
proxy:
kind: HTTPProxy
spec:
url: http://alertmanager:9093
allowedEndpoints:
- endpointPattern: /api/v2/alerts
method: GET
- endpointPattern: /api/v2/silences
method: GET
- endpointPattern: /api/v2/status
method: GETThere was a problem hiding this comment.
Added this paragraph and the read-only allowedEndpoints example to the datasource section in f7679f4.
| inhibited: false | ||
| ``` | ||
|
|
||
| This query returns the active alerts, but not the silenced or inhibited ones, that have the `critical` severity in the environments selected by the `env` variable. |
There was a problem hiding this comment.
unprocessed isn't set, so Alertmanager's default (true) applies and this query also returns the unprocessed (pending) alerts. Either add unprocessed: false to the example or mention them here, e.g.:
| This query returns the active alerts, but not the silenced or inhibited ones, that have the `critical` severity in the environments selected by the `env` variable. | |
| This query returns the active and unprocessed alerts, but not the silenced or inhibited ones, that have the `critical` severity in the environments selected by the `env` variable. |
| # Defaults to true. | ||
| enableSorting: <boolean> # Optional | ||
|
|
||
| # Initial sort of the table on this column |
There was a problem hiding this comment.
Only the first column with sort (and sorting enabled) sets the initial sort, see initialSort in AlertTablePanel.tsx:
| # Initial sort of the table on this column | |
| # Initial sort of the table on this column. Only the first column with `sort` and sorting enabled is used. |
| ```yaml | ||
| mode: <enum = "none" | "fingerprint" | "labels"> | ||
|
|
||
| # Labels whose values identify an alert, used with the "labels" mode |
There was a problem hiding this comment.
With mode: labels, omitting labels falls back to the fingerprint, but an empty list gives every alert the same key, so they all collapse into a single row (deduplicateAlerts in alert-table-model.ts). Worth saying that labels must be set with this mode, or guarding against the empty list in the panel.
There was a problem hiding this comment.
Documented in f7679f4 that the labels mode needs a non-empty labels list; I'll leave guarding the empty list in the panel to a follow-up.
| # Color of the values that don't match any override: "auto" computes a color from the value, | ||
| # "severity" uses the color of the severity level of the value (critical, error, warning, info, ...), | ||
| # and "manual" uses a gray color. |
There was a problem hiding this comment.
In severity mode, values that aren't a known severity level or alias (matched case-insensitively, e.g. crit, page, high) fall back to the auto color:
| # Color of the values that don't match any override: "auto" computes a color from the value, | |
| # "severity" uses the color of the severity level of the value (critical, error, warning, info, ...), | |
| # and "manual" uses a gray color. | |
| # Color of the values that don't match any override: "auto" computes a color from the value, | |
| # "severity" uses the color of the severity level of the value (critical, error, warning, info, ...) | |
| # and falls back to "auto" for other values, and "manual" uses a gray color. |
| # Colors applied before the mode, the first matching override wins | ||
| overrides: | ||
| - value: <string> | ||
| isRegex: <boolean> |
There was a problem hiding this comment.
Worth documenting the regex semantics: value is compiled as a JavaScript RegExp and tested without anchors, so db also matches mydb-1 (unlike the fully anchored =~ matchers of Alertmanager), and an invalid expression never matches.
| isRegex: <boolean> | |
| # When true, value is a JavaScript regular expression that can match any part of the label value: | |
| # use ^ and $ to match the whole value | |
| isRegex: <boolean> |
| - value: "page" | ||
| isRegex: false | ||
| color: "#d32f2f" |
There was a problem hiding this comment.
This override doesn't change anything: page is already an alias of critical in severity mode, and #d32f2f is already the critical color (label-colors.ts). A value the mode doesn't know would show what overrides are for, e.g.:
| - value: "page" | |
| isRegex: false | |
| color: "#d32f2f" | |
| - value: "P1" | |
| isRegex: false | |
| color: "#d32f2f" |
| # createdBy, startsAt, endsAt, duration or updatedAt | ||
| name: <string> | ||
| # Header of the column. Defaults to the name of the field, such as "Creator" for createdBy. |
There was a problem hiding this comment.
The default header isn't the field name but a readable label (DEFAULT_COLUMN_HEADERS):
| # Header of the column. Defaults to the name of the field, such as "Creator" for createdBy. | |
| # Header of the column. Defaults to a readable name of the field: "Creator", "Starts At", "Ends At", "Duration" or "Updated At". |
| # Defaults to true. | ||
| enableSorting: <boolean> # Optional | ||
| sort: <enum = "asc" | "desc"> # Optional |
There was a problem hiding this comment.
sort has no effect for now: the initial sort comes from the first column with sort, which is always the built-in status column (sort: asc in DEFAULT_SILENCE_COLUMNS, always prepended). I'd either document that here, or let a configured sort take precedence in the panel in a follow-up.
There was a problem hiding this comment.
Documented in f7679f4 that sort has no effect for now; letting a configured sort take precedence can be a follow-up.
| ) | ||
|
|
||
| func main() { | ||
| dashboard.New("Alertmanager Dashboard", |
There was a problem hiding this comment.
dashboard.New validates the name, so this returns "Alertmanager Dashboard" is not a correct name. It should match the regexp: ^[a-zA-Z0-9_.-]+$ (unnoticed since the example drops the error). Same at alerts-query.md:104, silences-query.md:54 and alert-table.md:108. Most other plugin docs share this pattern, so not blocking, but it would be nice not to copy it:
| dashboard.New("Alertmanager Dashboard", | |
| dashboard.New("alertmanager-dashboard", |
There was a problem hiding this comment.
Renamed it to alertmanager-dashboard in all 4 Go SDK pages in f7679f4; dashboard.New now returns no error for each of them.
Signed-off-by: Joshua (OpenClaw) <s3onghyun@users.noreply.github.com>
Nexucis
left a comment
There was a problem hiding this comment.
great ! Thank you @s3onghyun !
Description
Adds the missing user documentation for the Alertmanager plugin package:
docs/alertmanager/README.md(overview of the datasource, the alerts and silences queries, the AlertTable and SilenceTable panels and the two explorers),docs/alertmanager/model.md(YAML specification and example for each of the five kinds plus the column, deduplication and label-colour sub-specs), Go SDK pages for the four existing builders (datasource, alerts query, silences query, alert table; there is no SilenceTable builder yet, which the silences-query page says), and thedocs/nav.yamlentry in alphabetical position. Layout and tone follow the tempo and prometheus pages.Docs only, no code change. The model examples were validated with
cue vet -cagainst the plugin's own schemas, the Go SDK examples compile and run against the local module, and all links, anchors and nav paths resolve. I kept the repository's existing markdown conventions rather than the rewritesmake checkdocs(mdox) would apply, because that target also rewrites about 27 already-committed files onmain.Screenshots
n/a
Checklist
[<catalog_entry>] <commit message>naming convention using one of thefollowing
catalog_entryvalues:FEATURE,ENHANCEMENT,BUGFIX,BREAKINGCHANGE,DOC,IGNORE.UI Changes