Skip to content

[DOC] alertmanager: add plugin documentation - #934

Merged
Nexucis merged 2 commits into
perses:mainfrom
s3onghyun:fix/perses-am-docs-page
Nov 16, 2026
Merged

Nexucis merged 2 commits into
perses:mainfrom
s3onghyun:fix/perses-am-docs-page

Conversation

@s3onghyun

Copy link
Copy Markdown
Contributor

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 the docs/nav.yaml entry 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 -c against 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 rewrites make checkdocs (mdox) would apply, because that target also rewrites about 27 already-committed files on main.

Screenshots

n/a

Checklist

  • Pull request has a descriptive title and context useful to a reviewer.
  • Pull request title follows the [<catalog_entry>] <commit message> naming convention using one of the
    following catalog_entry values: FEATURE, ENHANCEMENT, BUGFIX, BREAKINGCHANGE, DOC,IGNORE.
  • All commits have DCO signoffs.

UI Changes

  • Changes that impact the UI include screenshots and/or screencasts of the relevant changes.
  • Code follows the UI guidelines.

Signed-off-by: Joshua (OpenClaw) <s3onghyun@users.noreply.github.com>

@Nexucis Nexucis left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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.yaml entries 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 duration column sorts its formatted value alphabetically, so 10h comes before 2h.
  • Once the sortMode: "status" fix mentioned in #933 lands, the Alert Table sortMode list here will need status too.


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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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: GET

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Added this paragraph and the read-only allowedEndpoints example to the datasource section in f7679f4.

Comment thread docs/alertmanager/model.md Outdated
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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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.:

Suggested change
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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Applied in f7679f4.

Comment thread docs/alertmanager/model.md Outdated
# Defaults to true.
enableSorting: <boolean> # Optional

# Initial sort of the table on this column

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Only the first column with sort (and sorting enabled) sets the initial sort, see initialSort in AlertTablePanel.tsx:

Suggested change
# 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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Applied in f7679f4.

```yaml
mode: <enum = "none" | "fingerprint" | "labels">

# Labels whose values identify an alert, used with the "labels" mode

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

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.

Comment thread docs/alertmanager/model.md Outdated
Comment on lines +183 to +185
# 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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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:

Suggested change
# 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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Applied in f7679f4.

# Colors applied before the mode, the first matching override wins
overrides:
- value: <string>
isRegex: <boolean>

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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.

Suggested change
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>

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Applied in f7679f4.

Comment thread docs/alertmanager/model.md Outdated
Comment on lines +220 to +222
- value: "page"
isRegex: false
color: "#d32f2f"

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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.:

Suggested change
- value: "page"
isRegex: false
color: "#d32f2f"
- value: "P1"
isRegex: false
color: "#d32f2f"

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Switched the example to P1 in f7679f4.

Comment thread docs/alertmanager/model.md Outdated
# createdBy, startsAt, endsAt, duration or updatedAt
name: <string>
# Header of the column. Defaults to the name of the field, such as "Creator" for createdBy.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

The default header isn't the field name but a readable label (DEFAULT_COLUMN_HEADERS):

Suggested change
# 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".

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Applied in f7679f4.

# Defaults to true.
enableSorting: <boolean> # Optional
sort: <enum = "asc" | "desc"> # Optional

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Documented in f7679f4 that sort has no effect for now; letting a configured sort take precedence can be a follow-up.

Comment thread docs/alertmanager/go-sdk/datasource.md Outdated
)

func main() {
dashboard.New("Alertmanager Dashboard",

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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:

Suggested change
dashboard.New("Alertmanager Dashboard",
dashboard.New("alertmanager-dashboard",

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

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>
@s3onghyun

Copy link
Copy Markdown
Contributor Author

Thanks for the thorough review @Nexucis! All the inline comments are addressed in f7679f4. The model examples still pass cue vet, and the Go SDK examples pass go vet.

@Nexucis Nexucis left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

great ! Thank you @s3onghyun !

@Nexucis
Nexucis merged commit f45205f into perses:main Nov 16, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants