Tag 7: karma
Ziel: karma läuft neben dem Alertmanager, zeigt alle Alarme als Dashboard und liest seine Einstellungen aus einer Datei. Du kennst die Oberfläche und die HTTP-API dahinter. · Dauer: ca. 45 min · Voraussetzung: Tag 6
Briefing
- karma ist ein Dashboard für den Alertmanager,
geschrieben in Go und React, entstanden bei Cloudflare (früher „unsee“).
Projekt:
github.com/prymitive/karma. - karma fragt die API v2 eines oder mehrerer Alertmanager in festen Abständen ab, fasst die Alarme zusammen und zeigt sie als Kacheln. Es ändert keine Alarme.
- Schreiben kann karma nur eines: Silences anlegen, ändern und beenden. Das geht entweder direkt vom Browser zum Alertmanager oder über karma als Proxy.
- Konfiguriert wird karma über eine YAML-Datei, über Umgebungsvariablen oder über Schalter. Für mehr als einen Alertmanager braucht es die Datei.
Browser ──► karma :8000 ── alle 30 s GET /api/v2/alerts/groups, /silences ──► alertmanager :9093
│
└── Silence anlegen (proxy: true) ── POST /api/v2/silences ──────►
Drill 1: Die schnellste Variante
Eine Umgebungsvariable reicht für den Anfang:
cd ~/am-lab
cat > dashboard.yaml <<'EOF'
services:
karma:
image: ghcr.io/prymitive/karma:v0.134
environment:
ALERTMANAGER_URI: http://alertmanager:9093
ports:
- "8000:8080"
EOF
echo " - dashboard.yaml" >> compose.yaml
docker compose up -d karma
docker compose logs --no-log-prefix karmaErwartet (gekürzt):
level=INFO msg="Version: v0.134"
level=INFO msg="Configured Alertmanager source" name=default cluster=default uri=http://alertmanager:9093 proxy=false readonly=false
level=INFO msg="Initial Alertmanager collection"
level=INFO msg="Upstream version" version=0.35.0 alertmanager=default
level=INFO msg="Got silences" alertmanager=default silences=3 duration=2.978019ms
level=INFO msg="Collected alert groups" alertmanager=default groups=2 duration=2.379345ms
level=INFO msg="Deduplicating alert groups" alertmanager=default groups=2
…
level=INFO msg="Starting HTTP server" address=[::]:8080
- karma lauscht im Container auf 8080. Der Port ist auf der VM schon von notes-api belegt, deshalb liegt karma außen auf 8000.
- Vor dem Start holt karma einmal alles ab. Erst danach nimmt es Anfragen an.
- Der Upstream heißt
default, weil du keinen Namen vergeben hast.
curl -s localhost:8000/health
curl -s localhost:8000/versionErwartet:
Pong
{
"version": "v0.134",
"golang": "go1.27.3"
}
Fortschritt speichern? Kostenlos registrieren
Drill 2: Die Konfigurationsdatei
mkdir -p karma
cat > karma/karma.yaml <<'EOF'
karma:
name: am-lab
alertmanager:
interval: 30s
servers:
- name: prod
uri: http://alertmanager:9093
external_uri: http://172.16.0.61:9093
timeout: 10s
proxy: true
log:
config: true
EOFkarma.namesteht im Titel des Browser-Tabs. Bei mehreren karma-Instanzen weißt du so, welche du vor dir hast.intervallegt fest, wie oft karma alle Alertmanager abfragt, höchstens15m.urinutzt karma selbst, also den Namen im Compose-Netz.external_urinutzt der Browser für Links in die Alertmanager-Oberfläche. Setze deine VM-Adresse ein.proxy: true: Silences schickt der Browser an karma, karma reicht sie weiter. Der Browser muss den Alertmanager dann nicht erreichen. An Tag 11 braucht das die Rechteprüfung.log.config: trueschreibt beim Start die gesamte Konfiguration ins Log, mit allen Standardwerten.
Der Compose-Baustein liest jetzt die Datei:
cat > dashboard.yaml <<'EOF'
services:
karma:
image: ghcr.io/prymitive/karma:v0.134
environment:
CONFIG_FILE: /etc/karma/karma.yaml
volumes:
- ./karma:/etc/karma:ro
ports:
- "8000:8080"
EOF
docker compose up -d karma
docker compose logs --no-log-prefix karma | grep -A9 'msg=alertmanager:'Erwartet:
level=INFO msg=alertmanager:
level=INFO msg=" interval: 30s"
level=INFO msg=" servers:"
level=INFO msg=" - cluster: \"\""
level=INFO msg=" name: prod"
level=INFO msg=" uri: http://alertmanager:9093"
level=INFO msg=" external_uri: http://172.16.0.61:9093"
level=INFO msg=" proxy_url: \"\""
level=INFO msg=" timeout: 10s"
level=INFO msg=" proxy: true"
karma hat keinen Reload. Nach jeder Änderung an der Datei startest du
den Container neu: docker compose restart karma.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Etwas zum Anschauen
Damit das Dashboard nicht leer ist, sorgst du für ein paar Alarme. Die Fehlerquote und den node-exporter kennst du:
NOTES_ERROR_RATE=0.3 docker compose up -d notes-api
docker compose stop node-exporterDazu Testalarme, die drei Stunden halten:
N=$(date -u +%Y-%m-%dT%H:%M:%SZ)
E=$(date -u -d '+3 hours' +%Y-%m-%dT%H:%M:%SZ)
amtool alert add alertname=PlatteVoll team=notes severity=warning instance=a \
--annotation='summary="Platte a zu 91 % voll"' --start=$N --end=$E
amtool alert add alertname=PlatteVoll team=notes severity=warning instance=b \
--annotation='summary="Platte b zu 92 % voll"' --start=$N --end=$E
amtool alert add alertname=PlatteVoll team=notes severity=warning instance=c \
--annotation='summary="Platte c zu 95 % voll"' --start=$N --end=$E
amtool alert add alertname=Werbeaktion team=marketing severity=warning \
--start=$N --end=$ETipp: Hast du zwischen zwei Tagen pausiert? Testalarme leben drei Stunden, die Silences aus Tag 5 zwei und 24 Stunden. Fehlen sie, legst du sie mit denselben Befehlen neu an, die Silences wie in Tag 5 Drill 3 mit
amtool silence add. Die Zahlen in den nächsten Tagen stimmen dann wieder.
Ausprobiert: Mit
--endallein setztamtool0.35 auch den Beginn auf das Ende. Der Alarm hat dannstartsAtin drei Stunden und sieht in karma seltsam aus. Gib--startimmer mit an.
Prometheus braucht für die Fehlerquote gut zwei Minuten. Danach
öffnest du http://172.16.0.61:8000 im Browser.
So liest du das Bild:
- Jede Kachel ist eine Alarmgruppe, so wie der
Alertmanager sie bildet. Der Titel sind die Labels aus
group_by, hieralertnameundenv. - Die Zahlen rechts im Titel: rot sind aktive Alarme,
grün unterdrückte. Bei
PlatteVollsind zwei aktiv, einer ist stumm. - Unter jedem Alarm stehen seine eigenen Labels. Labels, die alle Alarme einer Gruppe teilen, rutschen in die Fußzeile der Kachel.
- Silences erscheinen direkt am Alarm, mit Kommentar, Autor und Restlaufzeit. Der Balken darunter zeigt, wie viel der Laufzeit schon vergangen ist.
- Labels mit
@sind von karma:@receiverist der Receiver der Gruppe,@stateder Zustand,@alertmanagerspäter der Upstream.
Zwei Dinge fallen auf. Fast jede Gruppe steht
doppelt da, einmal mit @receiver: archiv
und einmal mit dem Receiver des Teams. karma bildet Gruppen pro
Receiver, und die Archiv-Route aus Tag 3 bekommt alles. Außerdem ist
NodeExporterDown beim Team plattform grün: Der Feierabend
aus Tag 5 hat die Gruppe stummgeschaltet, karma zählt das als
unterdrückt. Liest du werktags vor 18 Uhr oder am Wochenende, ist sie
rot, und in den Zählern der nächsten Tage fehlt ein unterdrückter Alarm.
Um beides kümmert sich Tag 8.
Ein Klick auf die Zahl links oben öffnet die Übersicht: die häufigsten Werte jedes Labels über alle Alarme.
Hier siehst du sofort, dass das Archiv die Hälfte aller Einträge stellt. Ein Klick auf einen Wert setzt ihn als Filter.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Die API hinter der Oberfläche
Alles, was die Oberfläche zeigt, liefert karma auch als JSON. Für Prüfungen von der Kommandozeile reichen drei Endpunkte.
Die Namen aller Labels, die gerade vorkommen:
curl -s localhost:8000/labelNames.json | jq -c .Erwartet:
["alertname","env","instance","job","severity","team"]
Die Zähler der Übersicht:
curl -s localhost:8000/counters.json | jq '.total'Erwartet:
14
Die Liste der Alarme, jeder als Liste seiner Labels:
curl -s localhost:8000/alertList.json | jq -c '.alerts[0]'Erwartet:
[{"name":"alertname","value":"NodeExporterDown"},{"name":"env","value":"prod"},{"name":"instance","value":"node-exporter:9100"},{"name":"job","value":"node"},{"name":"severity","value":"warning"},{"name":"team","value":"plattform"}]
Die Zahlen von API und Oberfläche können für einen Moment abweichen. Die Oberfläche holt neue Daten alle 30 Sekunden, karma selbst fragt den Alertmanager ebenfalls alle 30 Sekunden.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
curl -s localhost:8000/healthErwartet: Pong.
docker compose logs --no-log-prefix karma | grep 'Configured Alertmanager'Erwartet: eine Zeile mit name=prod und
proxy=true.
curl -s localhost:8000/labelNames.json | jq lengthErwartet: 6, karma kennt die Labels deiner Alarme.
Challenge
Finde nur mit curl, welche Alarme gerade unterdrückt
sind und wie oft jeder Name vorkommt.
Hinweis: counters.json und
alertList.json nehmen Filter als Parameter q,
genau wie die Suchleiste. Der Filter für den Zustand heißt
@state=suppressed. curl -G --data-urlencode
kodiert ihn korrekt.
Lösung
curl -s -G localhost:8000/counters.json --data-urlencode 'q=@state=suppressed' \
| jq -c '.counters[] | select(.name=="alertname") | .values[] | [.value, .hits]'Erwartet:
["PlatteVoll",2]
["Werbeaktion",2]
["NodeExporterDown",1]
PlatteVoll (Instanz a) und Werbeaktion sind
durch die Silences aus Tag 5 stumm, jeweils zweimal, weil beide Receiver
sie zeigen. NodeExporterDown einmal, nur in der Gruppe des
Teams plattform mit Feierabend. Im Archiv ist er aktiv.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- karma braucht nur Lesezugriff auf die Alertmanager-API. Mit
proxy: truemüssen die Browser der Nutzer den Alertmanager gar nicht erreichen. Das ist die bessere Netzwerk-Grenze. external_uriauf die Adresse setzen, die Menschen erreichen, also den Ingress oder DNS-Namen, nicht den internen Dienstnamen.- Pinne das Image auf eine Version (
v0.134), nicht auflatest.latestist bei karma der aktuelle Stand des main-Branches, nicht das letzte Release. /healthantwortet immer mitPong, auch wenn kein Alertmanager erreichbar ist. Ob die Upstreams leben, zeigt/metrics(Tag 12).