Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 4: Receiver und Templates

Ziel: Das Team notes bekommt zusätzlich eine E-Mail, und zwar eine, die ein Mensch nachts um drei versteht: eigener Betreff, eigener Text, gebaut mit einem Template. · Dauer: ca. 50 min · Voraussetzung: Tag 3

Briefing

  • Ein Receiver ist ein Name mit einer oder mehreren Integrationen: webhook, email, slack, msteamsv2, pagerduty, opsgenie, telegram und weitere. Ein Receiver darf mehrere davon gleichzeitig haben.
  • Jede Integration hat eingebaute Templates für Betreff und Text. Du kannst sie durch eigene ersetzen. Die Sprache ist Go-text/template.
  • Mailpit ist ein Mailserver für Tests. Er nimmt jede Mail an, stellt sie nie zu und zeigt sie in einer Weboberfläche und über eine API.
 Alertmanager ── Receiver team-notes ─┬─ webhook ─► alarm-log :5001/team-notes
                                      └─ email ───► mailpit :1025 (SMTP)
                                                      └─ Web/API :8025

Drill 1: Mailpit

cd ~/am-lab
cat > mail.yaml <<'EOF'
services:
  mailpit:
    image: axllent/mailpit:v1.33.1
    ports:
      - "8025:8025"
EOF
echo "  - mail.yaml" >> compose.yaml
docker compose up -d
curl -s localhost:8025/api/v1/messages | jq -c '{total}'

Erwartet:

{"total":0}

Port 1025 (SMTP) bleibt im Compose-Netz, nur die Weboberfläche ist von außen erreichbar: http://172.16.0.61:8025.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Ein Mail-Receiver

Zwei Änderungen in alertmanager/alertmanager.yml, am besten im Editor. Ganz oben, vor route:, kommt ein Abschnitt global:

global:
  smtp_smarthost: mailpit:1025
  smtp_from: [email protected]
  smtp_require_tls: false

route:
  …

Und der Receiver team-notes bekommt eine zweite Integration:

  - name: team-notes
    webhook_configs:
      - url: http://alarm-log:5001/team-notes
    email_configs:
      - to: [email protected]
  • global hält Werte, die für alle Receiver gelten. Der Mailserver gehört dazu.
  • smtp_require_tls: false, weil Mailpit im Lab kein TLS spricht. Ohne den Schalter verlangt der Alertmanager STARTTLS und scheitert.
amtool check-config alertmanager/alertmanager.yml | head -1
curl -s -X POST localhost:9093/-/reload
amtool alert add alertname=PlatteVoll team=notes severity=warning instance=a \
  --annotation='summary="Platte zu 91 % voll"'
amtool alert add alertname=PlatteVoll team=notes severity=warning instance=b \
  --annotation='summary="Platte zu 95 % voll"'

Nach 30 Sekunden:

curl -s localhost:8025/api/v1/messages | jq -r '.messages[].Subject'

Erwartet:

[FIRING:2] PlatteVoll (warning notes)

Der Standard-Betreff: Status, Anzahl, dann die Gruppen-Labels und die gemeinsamen Labels in Klammern. Den Text liefert die API ohne HTML:

curl -s localhost:8025/api/v1/message/latest | jq -r .Text

Erwartet (gekürzt):

2 alerts for alertname=PlatteVoll

View in Alertmanager ( http://172.16.0.61:9093/#/alerts?receiver=team-notes ) *[2] Firing* *Labels*
alertname = PlatteVoll
instance = a
severity = warning
team = notes
*Annotations*
summary = Platte zu 91 % voll
Source
…
Sent by Alertmanager ( http://172.16.0.61:9093 )

Brauchbar, aber lang. Was wirklich los ist, steht erst ganz unten.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Ein eigenes Template

Templates liegen in eigenen Dateien. Jede definiert mit define einen oder mehrere Bausteine:

mkdir -p alertmanager/templates
cat > alertmanager/templates/notes.tmpl <<'EOF'
{{ define "notes.subject" -}}
[{{ .Status | toUpper }}{{ if eq .Status "firing" }}:{{ .Alerts.Firing | len }}{{ end }}]
{{- " " }}{{ .CommonLabels.alertname }} ({{ .CommonLabels.env }}, Team {{ .CommonLabels.team }})
{{- end }}

{{ define "notes.text" -}}
{{ range .Alerts -}}
{{ if eq .Status "firing" }}FEUERT{{ else }}BEHOBEN{{ end }}: {{ .Annotations.summary }}
  seit:    {{ .StartsAt.Format "02.01.2006 15:04" }} UTC
  Labels:  {{ range .Labels.SortedPairs }}{{ .Name }}={{ .Value }} {{ end }}
  Runbook: {{ or .Annotations.runbook_url "keins" }}
{{ end -}}
Alertmanager: {{ .ExternalURL }}
{{- end }}
EOF
  • Der Punkt . ist die ganze Benachrichtigung, dieselben Daten wie im Webhook aus Tag 2: .Status, .Alerts, .CommonLabels, .ExternalURL.
  • {{- und -}} entfernen Leerraum vor oder nach dem Ausdruck. Ohne sie stünden Zeilenumbrüche im Betreff.
  • .Alerts.Firing ist die Liste der feuernden Alarme, len zählt sie.
  • or a "keins" nimmt den ersten Wert, der nicht leer ist.

Bevor ein Template in die Konfiguration kommt, prüfst du es mit Beispieldaten:

amtool template render --template.glob='alertmanager/templates/*.tmpl' \
  --template.text='{{ template "notes.text" . }}'

Erwartet:

FEUERT:
  seit:    16.11.2026 19:38 UTC
  Labels:  commonlabelkey1=commonlabelvalue1 commonlabelkey2=commonlabelvalue2 instance=foo.bar:1234 label1=value1 label2=value2
  Runbook: keins
BEHOBEN:
  seit:    16.11.2026 19:33 UTC
  Labels:  baz=qux commonlabelkey1=commonlabelvalue1 commonlabelkey2=commonlabelvalue2 foo=bar
  Runbook: keins
Alertmanager: https://example.com

Die Beispieldaten von amtool haben keine summary, deshalb steht nach FEUERT: nichts. Ein Tippfehler im Template würde hier als Fehler auffallen, nicht erst nachts.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Das Template benutzen

Wieder zwei Stellen in alertmanager/alertmanager.yml. Unter global kommt die Liste der Template-Dateien:

templates:
  - /etc/alertmanager/templates/*.tmpl

Der Mail-Eintrag von team-notes bekommt Betreff, Text und ein leeres HTML:

    email_configs:
      - to: [email protected]
        headers:
          Subject: '{{ template "notes.subject" . }}'
        text: '{{ template "notes.text" . }}'
        html: ''
  • Der Pfad gilt im Container. Das Verzeichnis alertmanager/ ist dort als /etc/alertmanager eingehängt.
  • amtool check-config prüft das Template nicht. Der Pfad stimmt nur im Container, auf der VM findet amtool keine Datei und zählt nur den Eintrag. Templates prüfst du deshalb immer mit amtool template render wie in Drill 3.
  • html: '' schaltet den HTML-Teil ab. Sonst schickt der Alertmanager zusätzlich sein Standard-HTML, und die meisten Mailprogramme zeigen nur das.
amtool check-config alertmanager/alertmanager.yml | grep -E 'templates|SUCCESS'
curl -s -X DELETE localhost:8025/api/v1/messages
curl -s -X POST localhost:9093/-/reload
NOTES_ERROR_RATE=0.5 docker compose up -d notes-api

Erwartet:

Checking 'alertmanager/alertmanager.yml'  SUCCESS
 - 1 templates
  SUCCESS

Nach etwa drei Minuten (Fehlerquote über zwei Minuten, for: 2m, dann group_wait):

curl -s localhost:8025/api/v1/messages | jq -r '.messages[].Subject'

Erwartet:

[FIRING:1] NotesHighErrorRate (prod, Team notes)
curl -s localhost:8025/api/v1/message/latest | jq -r .Text

Erwartet:

FEUERT: 47.96% der Anfragen an /notes scheitern
  seit:    16.11.2026 19:47 UTC
  Labels:  alertname=NotesHighErrorRate env=prod severity=warning team=notes
  Runbook: keins
Alertmanager: http://172.16.0.61:9093

Fünf Zeilen, die erste sagt alles. Schalte die Störung wieder ab:

docker compose up -d notes-api

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

amtool check-config alertmanager/alertmanager.yml | grep templates

Erwartet: - 1 templates.

curl -s localhost:8025/api/v1/message/latest | jq -r .Subject

Erwartet: ein Betreff in deinem Format, beginnend mit [FIRING:1].

curl -s localhost:8025/api/v1/message/latest | jq -c '{HTML}'

Erwartet: {"HTML":""}, die Mail hat nur Text.

Challenge

Ist die Fehlerquote vorbei, kommt keine Mail. Der Webhook dagegen meldet resolved. Finde heraus, warum, und sorge dafür, dass auch die Mail „BEHOBEN“ meldet. Schalte dafür die Störung noch einmal ein und erst nach deiner Änderung wieder ab.

Hinweis: amtool config show zeigt die Standardwerte jeder Integration. Vergleiche webhook_configs und email_configs.

Lösung

amtool config show | grep -A2 'email_configs'

Erwartet:

  email_configs:
  - send_resolved: false
    to: [email protected]

Webhooks melden die Auflösung standardmäßig, Mails nicht. Ergänze die Zeile im Mail-Eintrag:

      - to: [email protected]
        send_resolved: true
NOTES_ERROR_RATE=0.5 docker compose up -d notes-api
curl -s -X POST localhost:9093/-/reload

Warte, bis die Mail [FIRING:1] NotesHighErrorRate da ist (etwa drei Minuten), dann schalte die Störung ab:

docker compose up -d notes-api

Wenn die Fehlerquote abgeklungen ist und group_interval verstrichen ist:

curl -s localhost:8025/api/v1/messages | jq -r '.messages[].Subject'

Erwartet:

[RESOLVED] NotesHighErrorRate (prod, Team notes)
[FIRING:1] NotesHighErrorRate (prod, Team notes)
curl -s localhost:8025/api/v1/message/latest | jq -r .Text | head -1

Erwartet:

BEHOBEN: 9.144% der Anfragen an /notes scheitern

Die Zahl stammt aus der letzten Auswertung, bei der der Alarm noch feuerte. Danach schickt Prometheus keine neuen Annotations mehr. Ein Text wie „9 % scheitern“ in einer Entwarnung irritiert. Für resolved-Nachrichten schreibst du die Summary deshalb besser ohne Messwert.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Templates gehören wie Regeln ins Git und durch amtool template render in der CI.
  • Mails eignen sich für Warnungen, nicht für die Bereitschaft. Für critical nimmt man einen Pager-Dienst mit Eskalation (PagerDuty, Opsgenie, Grafana OnCall).
  • Für Chat gibt es fertige Integrationen: slack_configs, msteamsv2_configs, discord_configs, telegram_configs. Webhook-URLs mit Token gehören per url_file aus einer Datei geladen, nicht in die Konfiguration.
  • Eigene Templates zentral für alle Receiver definieren und nur referenzieren. Dann sieht jede Nachricht gleich aus, egal ob Mail oder Chat.