prometheus / prometheus/alertmanager

Incomplete AlertManager API Documentation

Open
#2,228 8 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

help wanted kind/documentation stale
Dominant language
Go
Stars
8.6k
Forks
2.5k
Avg merge
2d 6h
Merged PRs (30d)
61

Description

@mxinden
Either I don't know what I am doing or the Alert Manager API is not working as expected.
Your assistance is greatly appreciated.

I am trying to get a list of active alerts using a filter and it does not work as expected.
In all cases, I receive the complete list of active alarms.
Example 1:
curl -X GET http://10.44.0.3:9093/api/v2/alerts
Here I get the full list of active alerts.
So far so good!

Example 2:
curl -X GET http://10.44.0.3:9093/api/v2/alerts?name=my_receiver
Here I still get the full list of active alerts.

Example 2:
curl -X GET http://10.44.0.3:9093/api/v2/alerts?alertname=my_alert.*
Here I still get the full list of active alerts.

Unfortunately the AlertManager API documentation is poor vs Prometheus Server API documentation.
See link below:
https://prometheus.io/docs/alerting/management_api/

Below is the Alert Manager OPEN API spec but I don't know how to use it:
https://github.com/prometheus/alertmanager/blob/master/api/v2/openapi.yaml

/alerts:
get:
tags:
- alert
operationId: getAlerts
description: Get a list of alerts
parameters:
- in: query
name: active
type: boolean
description: Show active alerts
default: true
- in: query
name: silenced
type: boolean
description: Show silenced alerts
default: true
- in: query
name: inhibited
type: boolean
description: Show inhibited alerts
default: true
- in: query
name: unprocessed
type: boolean
description: Show unprocessed alerts
default: true
- name: filter
in: query
description: A list of matchers to filter alerts by
required: false
type: array
collectionFormat: multi
items:
type: string
- name: receiver
in: query
description: A regex matching receivers to filter alerts by
required: false
type: string

Can you provide examples showing how to construct alert queries with filters?

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the AlertManager API documentation and the /api/v2/openapi.yaml specification linked in the issue. Check the documented query parameters and matcher syntax, then add practical filter examples showing how to query alerts by name and receiver; the documentation is done when users can construct equivalent filtered requests without guessing.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.