grafana-observability

Lernen, entwerfen, aufbauen und betreiben Sie einen Grafana-Observability-Stack (Prometheus-Metriken, Loki-Logs, Tempo-Traces, Alloy-Sammlung, Grafana-Dashboards und Alerting), der als Code mit Terraform verwaltet wird.

Was ist grafana-observability?

Das Skill „Grafana-Observability“ befähigt einen KI-Agenten, produktionsreife Observability-Stacks auf Basis von Grafana zu lehren, zu entwerfen, zu erstellen und zu betreiben. Es deckt die gesamte Palette ab: Prometheus für Metriken, Loki für Logs, Tempo für Traces, Grafana Alloy als Collector sowie Grafana-Dashboards und Alerting – alles als Code mit Terraform verwaltet. Das Skill enthält 10 harte Regeln, die aus realen Incidents abgeleitet sind (z. B. keine `notification_settings` auf Alert-Regeln, keine Basic-Auth, Überprüfung von Drift vor jedem Apply). Es bietet einen detaillierten Arbeitsablauf für Änderungen (Frage → Query beweisen → coden → Drift prüfen → Plan anwenden → zurücklesen → committen) und eine klare Definition von „Done“ für Alert-Regeln, Dashboards und neue Exporteure/Datenquellen. Referenzdateien zu Architektur, Queries, Dashboards, Alerting, Infrastructure-as-Code und Meta-Monitoring ergänzen das Skill. Es eignet sich für Plattformen wie Claude Code, Cursor, Codex oder ähnliche KI-Assistenten für Entwickler und DevOps-Ingenieure. Das Skill priorisiert Lernen, Bauen (Dashboard, Alert, Pipeline, Terraform) und Planung einer Rollout-Strategie für Organisationen.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/louij2/grafana-observability-skill/tree/HEAD/.github/skills/grafana-observability

Installed? Explore more Produktivität & Zusammenarbeit skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht grafana-observability?

Dies sind die Praktiken eines produktionsreifen, selbst gehosteten Stacks: etwa 60 Dashboards, über 400 Alert-Regeln, 50 Scrape-Jobs sowie Logs und Traces, alles als Code verwaltet. Jede der folgenden Regeln existiert, weil ein Verstoß dagegen einen echten Incident verursacht hat. Das Warum wird erklärt, damit Sie Randfälle selbst beurteilen können.

Wählen Sie zunächst den Modus

  • Lernen („erkläre mir“, „erkläre“, „was ist“, „prüfe mich“): Folgen Sie references/learning-path.md. Vermitteln Sie eine Stufe nach der anderen und führen Sie das Labor in assets/lab/ aus. Überprüfen Sie das Verständnis, bevor Sie fortfahren. Werfen Sie nicht alle Stufen auf einmal hin.
  • Bauen (ein Dashboard, Alert, Pipeline, Terraform oder Rollout): Befolgen Sie den unten stehenden Workflow und öffnen Sie nur die Referenzdatei, die die Aufgabe benötigt.
  • Planung eines Rollouts in einer Organisation: references/implementation-plan.md.

Der Stack in einem Bild

 Apps / Hosts / Netzwerk-Kit / Cloud-APIs
      │ Metriken (Exporteure, /metrics)     │ Logs (Dateien, Docker, Syslog)   │ Traces (OTLP)
      ▼                                   ▼                                ▼
  Prometheus  ◄── scrape ──        Grafana Alloy (Collector: entdecken, umbenennen, schwärzen, versenden)
      │                                   │                                │
      │                                 Loki                             Tempo
      └──────────────┬────────────────────┴────────────────────────────────┘
                     ▼
                 Grafana  ── Dashboards, Explore, Alerting ──►  Contact Points (Chat, E-Mail, On-Call)
                     ▲
                 Terraform (Ordner, Datenquellen, Regeln, Routing) + Skripte (Dashboards) + Git

Details: references/architecture.md.

Die harten Regeln

  1. Code ist die Quelle der Wahrheit. Ändern Sie Alerting über Terraform und erstellen Sie Dashboards mit einem Generator-Skript oder JSON, das in Git lebt. Ein Klick in der UI geht beim nächsten Apply verloren oder wird, schlimmer noch, beim nächsten Apply stillschweigend rückgängig gemacht.
  2. Überprüfen Sie vor jedem Apply beide Arten von Drift. (a) Regeln, die live existieren, aber nicht im Code: Ein nicht gezieltes Apply löscht sie. (b) Regeln, die im Code stehen, aber live geändert wurden: Ein Apply macht sie rückgängig. Ein „No changes“-Plan beweist nichts über Regeln, die Terraform nie gesehen hat. Siehe references/as-code.md.
  3. Bewahren Sie den gespeicherten Plan. Führen Sie terraform plan -out aus und lehnen Sie dann jedes delete/replace ab, das Sie nicht beabsichtigt haben, und zwar für jede Ressource. Setzen Sie prevent_destroy auf Ordner. Das Löschen eines Grafana-Ordners löscht alle darin enthaltenen Dashboards und Regeln.
  4. Verwenden Sie ein Service-Account-Token, niemals admin:password. Wenn der Zustand unter Token-Auth erstellt wurde, plant ein Basic-Auth-Apply das Löschen und Neuerstellen von Ordnern, Contact Points und dem Policy-Baum. Das hat einmal 59 Dashboards und den gesamten Routing-Baum in einem einzigen Apply gelöscht.
  5. Setzen Sie niemals notification_settings (einen Contact Point) auf eine Regel. Eine Regel, die dies hat, umgeht den gesamten Policy-Baum vollständig. Sie entgeht dem Severity-Routing, Wiederholungsintervallen und Mute-Zeitplänen. In einem Fall taten dies 196 von 217 Regeln und niemandem fiel es auf.
  6. Setzen Sie den Schwellwert in Grafanas Threshold-Stage, nicht innerhalb des PromQL. Mit expr > 90 liefert ein gesunder Host keine Reihe, was Grafana als NoData interpretiert, nicht als OK. Fragen Sie den Rohwert ab und vergleichen Sie ihn in Stufe C.
  7. Routen Sie nach Handlungsbedarf und behandeln Sie Wiederholungsintervalle als den wirklichen Hebel. Verwenden Sie severity (critical/warning/info) plus urgency=backlog für chronische, bekannte Probleme. Die meisten Alert-Benachrichtigungen sind erneute Benachrichtigungen über etwas bereits Bekanntes. Wiederholen Sie kritische Alerts täglich und Warnungen wöchentlich, nicht stündlich.
  8. Eskalation sollte eine Verzögerung sein, und eine Silence ist die Bestätigung. Die Page-Route verwendet group_wait von etwa 15 Minuten, sodass sie nur dann eine Seite sendet, wenn der Alert immer noch feuert und nicht stummgeschaltet ist. Ereignisgesteuerte Regeln benötigen keep_firing_for ≥ die Wartezeit, sonst werden sie aufgelöst, bevor sie jemals eskalieren.
  9. Überwachen Sie die Überwachung. Achten Sie auf Evaluierungsfehler, Zustellungsfehler von Benachrichtigungen, unterdrückte (stummgeschaltete) Alerts, veraltete Exporteure und gestoppte Backups. Ein stilles Alerting-System sieht genauso aus wie ein gesundes. Siehe references/meta-monitoring.md.
  10. Verifizieren Sie, vertrauen Sie nicht. Führen Sie jede Panel- oder Alert-Abfrage vor dem Schreiben gegen die Datenquelle aus. Lesen Sie nach jedem API-Schreibvorgang das Objekt zurück und bestätigen Sie, dass Ihre Änderung darin enthalten ist: Die POST-Antwort sagt Ihnen nicht, welcher Inhalt hochgeladen wurde. Zustimmung zwischen zwei Personen oder zwei Sitzungen ist keine Verifikation; ein Befehl ist es.

Arbeitsablauf für jede Änderung

  1. Formulieren Sie die Frage, die das Panel oder der Alert beantwortet, und wer darauf reagiert. Wenn niemand auf einen Alert reagieren würde, handelt es sich um ein Dashboard-Panel, nicht um einen Alert.
  2. Beweisen Sie die Abfrage in Explore oder über die Datenquellen-Proxy-API. Überprüfen Sie, dass sie Daten zurückgibt, dass die Labels diejenigen sind, nach denen Sie gruppieren oder routen werden, und wie sie sich verhält, wenn sie gesund ist (leer? null?).
  3. Schreiben Sie es in Code: eine Terraform-Regelgruppe, ein Dashboard-Generator oder eine Alloy-Konfiguration. Folgen Sie references/alerting.md oder references/dashboards.md.
  4. Überprüfen Sie Drift, dann terraform plan -out=tfplan. Lesen Sie jeden aufgeklappten ~-Block, besonders bei grafana_notification_policy, denn dieser entscheidet, wo jeder Alert hingeht.
  5. Wenden Sie den gespeicherten Plan mit einem Service-Account-Token an. Verwenden Sie -target, wenn Sie unsicher sind.
  6. Lesen Sie es zurück aus der API, bestätigen Sie, dass die Regel evaluiert (Status ist nicht Error/NoData), und lösen Sie für Alerts einen End-to-End-Test bis zum echten Contact Point aus.
  7. Committen Sie mit dem Warum. Hinterlassen Sie einen Kommentar im Code, wo immer eine Entscheidung falsch aussieht, aber bewusst getroffen wurde.

Abschlussdefinition

Alert-Regel: in Terraform; severity-Label gesetzt; Summary- und Description-Templates enthalten den betroffenen Host oder Dienst und den aktuellen Wert; no_data_state bewusst gewählt; for lange genug,

um nicht zu flattern; über den Baum geroutet (kein pro-Regel-Contact-Point); ein Runbook-Link oder ein erster Schritt in der Beschreibung; End-to-End getestet; es doppelt keine Seite mit einer bestehenden Regel.

Dashboard: in Git (generiert oder mit entfernter ID/Version exportiert); im richtigen Ordner; mit dem Übersichts-Hub verlinkt und wieder zurück; Variablen für Umgebung/Host; jedes Panel hat einen Titel, der eine Frage stellt oder beantwortet; Einheiten und Schwellwerte gesetzt; keepTime bei Links.

Neuer Exporter oder neue Datenquelle: mit stabilen Labels (env, team, service, role) gescrapt; durch die Fleet-up == 0-Regel abgedeckt (keine separate hinzufügen); wenn es eine Metrik für den letzten Lauf oder Aktualität gibt, eine Staleness-Regel; zum Meta-Monitoring-Audit hinzugefügt; Datenquelle hat eine feste UID.

Referenzindex

DateiÖffnen, wenn …
learning-path.mdLehren oder Lernen, Stufe für Stufe mit Laboren
architecture.mdKomponenten, Labels, Aufbewahrung, Auth, HA auswählen
queries.mdPromQL oder LogQL schreiben oder eine Abfrage sieht falsch aus
dashboards.mdEin Dashboard erstellen oder überprüfen
alerting.mdRegeln, Routing, Contact Points, Silences, Ermüdung
as-code.mdTerraform, API, Backups, Drift, Wiederherstellungen
meta-monitoring.mdNachweisen, dass die Überwachung selbst funktioniert
implementation-plan.mdGrafana in ein Team oder Unternehmen einführen

Assets: assets/lab/ ist ein lokales Docker-Compose-Labor. assets/terraform-starter/ ist ein startbereiter Terraform-Stack mit den sicheren Standardeinstellungen.

Verwandte Skills