Skip to content

AGENTS.md

Latest commit

 

History

History
155 lines (120 loc) · 8.22 KB

AGENTS.md

File metadata and controls

155 lines (120 loc) · 8.22 KB
Raw

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