Zum Inhalt springen
Trainingslager IT-Trainingslager

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 karma

Erwartet (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/version

Erwartet:

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
EOF
  • karma.name steht im Titel des Browser-Tabs. Bei mehreren karma-Instanzen weißt du so, welche du vor dir hast.
  • interval legt fest, wie oft karma alle Alertmanager abfragt, höchstens 15m.
  • uri nutzt karma selbst, also den Namen im Compose-Netz. external_uri nutzt 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: true schreibt 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-exporter

Dazu 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=$E

Tipp: 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 --end allein setzt amtool 0.35 auch den Beginn auf das Ende. Der Alarm hat dann startsAt in drei Stunden und sieht in karma seltsam aus. Gib --start immer mit an.

Prometheus braucht für die Fehlerquote gut zwei Minuten. Danach öffnest du http://172.16.0.61:8000 im Browser.

karma mit einem Alertmanager: jede Kachel ist eine Alarmgruppe

So liest du das Bild:

  • Jede Kachel ist eine Alarmgruppe, so wie der Alertmanager sie bildet. Der Titel sind die Labels aus group_by, hier alertname und env.
  • Die Zahlen rechts im Titel: rot sind aktive Alarme, grün unterdrückte. Bei PlatteVoll sind 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: @receiver ist der Receiver der Gruppe, @state der Zustand, @alertmanager spä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.

Die Übersicht: welche Labels wie oft vorkommen

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/health

Erwartet: 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 length

Erwartet: 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: true müssen die Browser der Nutzer den Alertmanager gar nicht erreichen. Das ist die bessere Netzwerk-Grenze.
  • external_uri auf 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 auf latest. latest ist bei karma der aktuelle Stand des main-Branches, nicht das letzte Release.
  • /health antwortet immer mit Pong, auch wenn kein Alertmanager erreichbar ist. Ob die Upstreams leben, zeigt /metrics (Tag 12).