prometheus/alertmanager

What it does

Alertmanager is the alert-handling component of the Prometheus stack. Client applications such as Prometheus send alerts to it; it deduplicates and groups those alerts, routes them through a YAML-configured route tree, and delivers notifications to receivers including email, PagerDuty, OpsGenie, and generic webhooks L5-L7. It also manages silences and inhibition rules, so that, for example, warning notifications can be muted while a related critical alert is firing.

It is aimed at operators and platform teams running Prometheus who need a central place to decide who gets notified about which alerts, and how often. A bundled command-line client, amtool, talks to the Alertmanager API to inspect alerts, manage silences, render templates, and test routing decisions.

Quick start

The quickest way to try it is the published container image L23-L27:

docker run --name alertmanager -d -p 127.0.0.1:9093:9093 quay.io/prometheus/alertmanager

The web UI is then available at http://localhost:9093/. The default configuration has no useful receivers, so for real use write a YAML config and start the binary with --config.file=<your_file>.

A minimal config needs global settings for email if you use email receivers, a root route with a receiver, and a receivers list. The root route must have no matchers and must name a receiver; alerts that match nothing else fall through to it. Routing, grouping, and inhibition behavior are configured through nested routes, group_by, group_wait, group_interval, repeat_interval, and inhibit_rules L52-L177. A representative example is included in the README L48-L178.

To build from source you need Go and Node.js with npm L31-L41:

git clone https://github.com/prometheus/alertmanager.git
cd alertmanager
make build
./alertmanager --config.file=<your_file>

amtool is included with releases; it can also be installed with go install github.com/prometheus/alertmanager/cmd/amtool@latest. Point it at an instance via its config file, e.g. alertmanager.url: "http://localhost:9093", then run commands such as amtool alert to list firing alerts or amtool silence add alertname=Test_Alert to create a silence L204-L257.

Configuration and API

Configuration is YAML-based, and the full reference lives in the Prometheus documentation L48-L51. The HTTP API is v2, mounted under /api/v2; its OpenAPI spec is in the repository and can be used to generate clients in major languages L179-L199. APIv1 was deprecated in 0.16.0 and removed as of 0.27.0. If --web.route-prefix is set, API routes inherit that prefix. An experimental ConnectRPC API exposes Connect and gRPC-Web under /api/, plus native gRPC, health, and reflection at the server root.

amtool can also render notification templates and test routing: amtool config routes test --config.file=doc/examples/simple.yml --tree --verify.receivers=team-X-pager service=database owner=team-X prints the matching receivers and exits nonzero on a mismatch L326-L340.

High availability

Alertmanager can run as a cluster of peers, enabled by default. The cluster needs both UDP and TCP on the clustering port (default 9094); whitelist or expose both protocols if firewalling or containerizing. Peers are configured with --cluster.peer, and the listen address is set with --cluster.listen-address (empty string disables HA) L342-L399.

When using HA, point Prometheus at the full list of Alertmanager instances rather than putting a load balancer in front of them: all alerts are expected to reach all Alertmanagers. For a local three-node cluster, the repository includes a Procfile usable with goreman. Setting --cluster.listen-address= turns HA off L400-L403.

Constraints

• Building from source requires Go plus Node.js/npm; this is only needed for source builds, not for the precompiled binaries or container images.
• HA clustering requires both UDP and TCP on the clustering port; a TCP-only firewall rule will break gossip.
• Plaintext h2c for the experimental ConnectRPC listener provides neither encryption nor peer authentication; expose it only on trusted networks or behind a TLS-terminating proxy L179-L199.
• cluster.advertise-address is required when the instance lacks an RFC 6890 address with a default route L342-L399.
• License is Apache-2.0 L419-L425.

HotRepo's take

This is a long-standing infrastructure project rather than a new repository: created in 2013, it has 8,698 stars and 2,505 forks. In HotRepo's Go weekly snapshot dated 2026-11-12, it recorded 19 new stars and a best position of 12 on that Go language list; there is no recorded all-language daily rank, so the Go weekly figure should not be read as a broad trending position. The project's relevance is structural: it is the alert-routing layer most Prometheus deployments eventually need, and the README reflects that maturity with documented HA clustering, an OpenAPI spec, and a bundled CLI.