alertmanager

# AGENTS.md

Guidance for AI coding agents working in this repository. Keep this file concise and current. For end‑user docs, see `README.md` and https://prometheus.io/docs/alerting/alertmanager/.

## Project overview

Alertmanager handles alerts sent by clients such as Prometheus. It deduplicates, groups, routes, silences, and inhibits alerts, and dispatches them to receiver integrations (email, PagerDuty, Slack, webhook, etc.).

- Language: Go (see `go.mod` for the required version, currently `go 1.25`).
- Frontend (legacy): Elm app under `ui/app/` (Node version pinned in `.nvmrc`).
- Frontend (new): React + TypeScript + Mantine under `ui/mantine-ui/`.
- API: OpenAPI v2 spec in `api/v2/openapi.yaml`; Go server/client/models are generated via `scripts/swagger.sh`.
- Module path: `github.com/prometheus/alertmanager`.

## Repository layout

Top‑level packages worth knowing:

- `cmd/alertmanager/` — main binary entry point (`main.go`); thin wrapper that parses flags and calls `app`.
- `app/` — embeddable Alertmanager runtime extracted from `cmd/alertmanager`. Owns the process lifecycle (`New`/`Start`/`Stop`/`Reload`/`Run`), subsystem wiring (`setup`), config-reload subgraph (`reloader`), listeners and `Options`. Lets tests and other binaries run Alertmanager in‑process. See https://github.com/prometheus/alertmanager/issues/406.
- `cmd/amtool/` — CLI for interacting with the Alertmanager API.
- `api/` — HTTP API. `api/v2/` is the active API; `api/v1_deprecation_router.go` only returns deprecation responses.
- `cli/` — `amtool` command implementations.
- `cluster/` — HA gossip clustering (memberlist-based).
- `config/` — YAML config parsing, validation, secrets, coordinator.
- `dispatch/` — routing tree, alert grouping, dispatcher loop.
- `inhibit/` — inhibition rule engine.
- `mute/`, `silence/`, `timeinterval/` — muting, silences (with nflog), time‑based mutes.
- `nflog/` — notification log (persisted dedup state).
- `notify/` — notification pipeline plus one subpackage per integration (`slack`, `pagerduty`, `email`, `webhook`, `discord`, `jira`, `msteams`, `msteamsv2`, `opsgenie`, `pushover`, `rocketchat`, `sns`, `telegram`, `victorops`, `webex`, `wechat`, `mattermost`, `incidentio`).
- `template/` — notification templating (Go templates + default email template). `template/email.tmpl` is generated from `template/email.html`.
- `provider/mem/` — in‑memory alert provider (the only provider).
- `store/` — alert/silence store helpers.
- `types/` — core domain types (`Alert`, `Silence`, `Matcher`, ...).
- `matcher/` — label matcher parsing (used by routes, silences, inhibitions).
- `featurecontrol/` — feature flags wired through `--enable-feature`.
- `limit/`, `httpserver/`, `tracing/` — server plumbing.
- `ui/web.go` — embeds the built UI assets and serves them.
- `examples/`, `doc/examples/` — example configs and HA setups.
- `test/with_api_v2/` and `test/cli/` — integration/e2e tests.

Generated code (do not hand‑edit):

- `api/v2/{models,restapi,client}/` — regenerated by `scripts/swagger.sh` from `api/v2/openapi.yaml`.
- `ui/app/src/Data/` — Elm types generated from the OpenAPI spec.
- `template/email.tmpl` — generated from `template/email.html` via `template/Makefile`.
- `cluster/clusterpb/cluster.pb.go`, `nflog/nflogpb/nflog.pb.go`, `silence/silencepb/silence.pb.go` — regenerate via `scripts/genproto.sh` if the `.proto` schema must change.

## Common commands

Builds and tests are driven by the shared `Makefile.common` plus the repo‑specific `Makefile`.

- `make build` — build `alertmanager` and `amtool` (also builds Elm UI assets).
- `make build-all` — UI assets + regenerated API + binaries.
- `make build BINARIES=amtool` — build a single binary.
- `make assets` — regenerate Elm `Data` types and `template/email.tmpl`.
- `make apiv2` — regenerate `api/v2/{models,restapi,client}` from `api/v2/openapi.yaml` (runs `scripts/swagger.sh`; needs Docker).
- `make test` — full Go test suite (`go test ./...`) plus UI tests.
- `make test-short` (via `Makefile.common`) — `go test -short ./...`.
- `make lint` — `golangci-lint run` (version pinned in `Makefile.common`) plus UI lint.
- `make common-format` — `go fmt` + `golangci-lint fmt` (gofumpt + goimports with local prefix `github.com/prometheus/alertmanager`).
- `make fuzz-config` — short fuzz run over `./config`.
- `make clean` — remove generated API code, generated email template, and UI build output.

Run a single Go test package or test:

```
go test ./notify/slack/...
go test ./dispatch -run TestDispatcherRace -v
```

Run the UI dev servers directly when iterating on the frontend:

```
# Legacy Elm UI
cd ui/app && make build         # see ui/app/CONTRIBUTING.md
# New Mantine UI
cd ui/mantine-ui && npm install && npm run dev
```

Run Alertmanager locally:

```
./alertmanager --config.file=doc/examples/simple.yml
# multi-node HA via Procfile (requires goreman):
goreman start
```

## Conventions

- Follow the lint rules in `.golangci.yml`. Notable forbidden imports (enforced by `depguard`):
  - Use `github.com/stretchr/testify/require`, not `.../testify/assert`.
  - Use `github.com/go-kit/log`, not `github.com/go-kit/kit/log`.
  - Use the standard `errors`/`fmt`, not `github.com/pkg/errors`.
- Formatting: `gofumpt` + `goimports` with local prefix `github.com/prometheus/alertmanager`. Run `make common-format` before committing.
- Comments on exported identifiers must be full sentences ending in a period (`godot` lint).
- Logging uses `log/slog` (`sloglint`). Prefer structured key/value logging.
- Errors: wrap with `fmt.Errorf("...: %w", err)` and check with `errors.Is`/`errors.As` (`errorlint`).
- Keep package‑level documentation up to date (`revive: package-comments`).
- Tests live next to the code as `*_test.go`. Larger integration tests live under `test/`. The `notify/test` package provides shared testing helpers for notifier integrations.

## When changing the API

1. Edit `api/v2/openapi.yaml`.
2. Run `make apiv2` to regenerate `api/v2/{models,restapi,client}` (requires Docker; see `scripts/swagger.sh`).
3. Run `make assets` so the Elm UI's `Data` types stay in sync.
4. Update `api/v2/api.go` handlers for any new operations.
5. Run `make test lint`.

Do not hand‑edit generated files under `api/v2/models`, `api/v2/restapi`, `api/v2/client`, or `ui/app/src/Data`.

## When adding or modifying a notifier

- Each integration lives in its own package under `notify/<name>/`.
- Add config in `config/notifiers.go` (struct, validation, defaults) and wire it into `config/config.go` receivers.
- Register the notifier in `cmd/alertmanager/main.go` where receivers are built.
- Add unit tests in the notifier package; reuse helpers from `notify/test/`.
- Update `template/default.tmpl` only if you are introducing new default templates.
- Note the change in `CHANGELOG.md` under the unreleased section.

## When touching configuration

- `config/config.go` owns top‑level YAML parsing; field changes typically need:
  - Struct + `yaml` tags.
  - `UnmarshalYAML` validation.
  - Defaults in `DefaultGlobalConfig` / receiver defaults.
  - Tests in `config/config_test.go`, possibly `testdata/` fixtures.
- Validate behaviour with `make fuzz-config` for parser changes.

## CI expectations

GitHub Actions and CircleCI run build, tests, and `golangci-lint`. Before pushing:

```
make common-format
make lint
make test
```

If you regenerate API code or UI data, commit the regenerated files alongside the source changes.

## Things to avoid

- Don't reintroduce APIv1; it was removed in 0.27.0. The only thing left under `api/v1_deprecation_router.go` is a deprecation responder.
- Don't bypass the notification pipeline (`notify/notify.go`) — new stages should be added as `notify.Stage` implementations.
- Don't add new top‑level dependencies without checking `.golangci.yml` `depguard` rules and `go.mod` minimums.
- Don't commit generated artifacts unless the corresponding source (`openapi.yaml`, `email.html`, etc.) changed in the same commit.

## Useful references

- Architecture diagram: `doc/arch.svg` (source `doc/arch.xml`).
- Example configs: `doc/examples/simple.yml`, `examples/ha/`, `examples/webhook/`.
- Maintainers and ownership: `MAINTAINERS.md`, `CODEOWNERS`.
- Release process: `RELEASE.md`.
- UI contributing guide: `ui/app/CONTRIBUTING.md`.