prometheus/alertmanager
1
0
Fork 0
mirror of https://github.com/prometheus/alertmanager.git synced 2026-02-05 15:45:34 +01:00
Code Issues Releases Activity

Improve docs for client behavior

Browse Source 
This commit updates the docs for client behavior, and describes a
number of the more nuanced semantics expected from clients to ensure
notifications are delivered as expected.

Signed-off-by: George Robinson <george.robinson@grafana.com>
This commit is contained in:
George Robinson
2025-03-11 10:45:50 +00:00
parent 56dace4f61
commit 8343ee691c
2 changed files with 79 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
docs/alerts_api.md Normal file
View File

@@ -0,0 +1,79 @@
---
title: Alerts API
sort_rank: 6
nav_icon: sliders
---
**Important**: Prometheus takes care of sending alerts to the Alertmanager.
It is recommended to configure alerting rules in Prometheus based on time
series data instead of sending alerts to the Alerts API, as Prometheus supports
a number of special cases to make sure alerts are delivered even if Alertmanager
crashes or restarts.
# Alerts API
You send alerts to Alertmanager via APIv2. The APIv2 is specified as an
OpenAPI specification that can be found [here
](https://github.com/prometheus/alertmanager/blob/master/api/v2/openapi.yaml).
APIv1 was deprecated in Alertmanager version 0.16.0 and removed in Alertmanager
version 0.27.0.
To send alerts to APIv2 make a POST request to `api/v2/alerts`. You must set
the `Content-Type` header to `application/json`, and send JSON data containing
an array of alerts.
Here is an example:
```json
[
{
"labels": {
"alertname": "<required_value>",
"<name>": "<value>",
...
},
"annotations": {
"<name>": "<value>",
},
"startsAt": "<RFC3339>",
"endsAt": "<RFC3339>",
"generatorURL": "<value>"
},
...
]
```
All alerts have labels, annotations, an optional `startsAt` timestamp and an
optional `endsAt` timestamp. All timestamps are expected in the RFC3339 format.
Labels are used to deduplicate identical instances of the same alert, while
annotations are used to include other information about the alert, such as a
summary, description or a URL to a runbook.
The `startsAt` timestamp is the time the alert fired. If omitted, Alertmanager
sets `startsAt` to the current time.
The `endsAt` timestamp is the time the alert should be resolved. If omitted,
Alertmanager sets `endsAt` to the current time + `resolve_timeout`.
The `generatorURL` is a unique URL which links to the source of the alert. For
example, it might link to the firing rule in Prometheus.
## Expectations from clients
Clients are expected to re-send firing alerts to the Alertmanager at regular
intervals until the alert is resolved.
The exact interval depends on a number of variables such as the `endsAt`
timestamp, or if omitted the value of `resolve_timeout`. If the `endsAt`
timestamp is omitted, the Alertmanager will update the existing `endsAt`
timestamp for the alert to the current time + `resolve_timeout`.
Firing alerts are resolved once their `endsAt` timestamp has elapsed.
To ensure resolved notifications are sent for resolved alerts, clients are also
expected to re-send resolved alerts to the Alertmanager for up to 5 minutes
after the alert has resolved. As the Alertmanager is stateless, this ensures
that a resolved notification is sent even if the Alertmanager crashes or is
restarted.

54
docs/clients.md
View File

@@ -1,54 +0,0 @@
---
title: Clients
sort_rank: 6
nav_icon: sliders
---
# Sending alerts
__**Disclaimer**: Prometheus automatically takes care of sending alerts
generated by its configured [alerting
rules](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/). It is highly
recommended to configure alerting rules in Prometheus based on time series data
rather than implementing a direct client.__
You send alerts to Alertmanager via API v2. The scheme for v2 is specified as
an OpenAPI specification that can be found [here
](https://github.com/prometheus/alertmanager/blob/master/api/v2/openapi.yaml).
API v1 was deprecated in Alertmanager version 0.16.0 and removed in Alertmanager
version 0.27.0.
Clients are expected to continuously re-send alerts as long as they are still
active (usually on the order of 30 seconds to 3 minutes). Clients can push a
list of alerts to Alertmanager via a POST request.
The labels of each alert are used to identify identical instances of an alert
and to perform deduplication. The annotations are always set to those received
most recently and are not identifying an alert.
Both `startsAt` and `endsAt` timestamp are optional. If `startsAt` is omitted,
the current time is assigned by the Alertmanager. `endsAt` is only set if the
end time of an alert is known. Otherwise it will be set to a configurable
timeout period from the time since the alert was last received.
The `generatorURL` field is a unique back-link which identifies the causing
entity of this alert in the client.
```json
[
{
"labels": {
"alertname": "<requiredAlertName>",
"<labelname>": "<labelvalue>",
...
},
"annotations": {
"<labelname>": "<labelvalue>",
},
"startsAt": "<rfc3339>",
"endsAt": "<rfc3339>",
"generatorURL": "<generator_url>"
},
...
]
```