Diagramme von Grafana-Metriken erstellen
Überblick
Erzeugt ein dunkel thematisiertes, im Grafana-Stil gehaltenes PNG-Liniendiagramm aus einer PromQL-Abfrage, die über den Grafana-Datenquellen-Proxy abgerufen wird (so ist kein direkter Prometheus-Netzwerkzugriff erforderlich, das Grafana-SA-Token reicht aus). Reproduzierbar und skriptbar, im Gegensatz zu einem manuellen Screenshot. Kann das Ergebnis direkt an ein Jira-Ticket anhängen.
Erstellen Sie zuerst einen Schnappschuss, wenn ein Panel es bereits zeigt. Grafana Cloud Stacks verfügen über serverseitiges Rendering, daher gibt gcx dashboards snapshot dort das echte Panel als PNG zurück. Diese Fähigkeit ist für das, was ein Schnappschuss nicht liefern kann: einen Seiten-an-Seiten-Vergleich über Abfragen oder Zeitbereiche hinweg, den kein einzelnes Panel kodiert, und für selbst gehostete Instanzen ohne das Image Renderer-Plugin, bei denen der Schnappschuss mit einem Fehler abbricht.
Vorbereitung
Jeder Grafana-Aufruf hier erfolgt über gcx. Überprüfen Sie es einmal pro Sitzung:
command -v gcx >/dev/null || { echo "installieren: brew install gcx"; exit 1; }
gcx config check || { echo "nicht bereit: gcx login"; exit 1; }
Holen Sie sich die Abfrage richtig, bevor Sie sie zeichnen. Diese Fähigkeit rendert jede PromQL, die Sie übergeben, und eine falsche Abfrage ist hier schlimmer als in einem Dashboard: Das PNG landet in einem Ticket als eingefrorener Beweis, den niemand wiederholt, und es sieht offiziell aus. ERFORDERLICHER HINTERGRUND für die Abfrage selbst: Verwenden Sie die Fähigkeit grafana-dashboards, Abschnitte PromQL-Grundlagen, Aggregationsfallen und Verteilungen und Enden lesen. Diejenigen, die bei einem Vergleichsdiagramm beißen: Aggregate nach rate und niemals davor, umschließen Sie beide Seiten mit max by (...), wenn ein Rollout zwei Serien pro Pod hinterlässt, niemals histogram_quantile eines Basis-2-Exponential-Histogramms, und geben Sie jeder Unterabfrage einen expliziten Schritt.
Wann verwenden
- Vergleich von 2+ Serien: Version A vs B, Canary vs Kontrolle, Vorher/Nachher einer Änderung.
- Anhängen von Beweisen an ein Jira-Ticket, MR oder Incident-Bericht.
- Grafana-Panel-Rendering schlägt fehl (
gcx dashboards snapshotgibt Fehler: kein Image Renderer in diesem selbst gehosteten Kontext).
Nicht für: interaktive Erkundung (Grafana verwenden), Einzelwert-/Tabellendaten oder einen Screenshot eines vorhandenen Panels auf Grafana Cloud (gcx dashboards snapshot).
Einrichtung (einmalig)
matplotlib ist erforderlich. Falls nicht vorhanden, verwenden Sie eine isolierte venv (verschmutzen Sie nicht das systemweite Python):
python3 -m venv ${CLAUDE_SKILL_DIR}/.venv
${CLAUDE_SKILL_DIR}/.venv/bin/pip install -q matplotlib
Kurzreferenz
| Bedarf | Flag |
|---|---|
| Welche Datenquelle | --datasource-uid (finden über gcx datasources list oder Panel-Abfragen) |
| Die Abfrage | --expr 'PromQL' |
| Zeitfenster | --start now-6h --end now --step 60 |
| Serienbeschriftungsquelle | --legend-key instance (Standard; jedes Metrik-Label) |
| Schönere Namen | --rename '{"raw-value":"Schöner Name"}' |
| Pro-Serie Mittelwert/Min/Max | nach dem Speichern auf stdout ausgegeben (keine zusätzliche Abfrage erforderlich) |
| Markierung am Maximum | --annotate-max "Text" |
| Welches Grafana | --grafana-url https://<host>: verwendet den gcx-Kontext, dessen Server diesen Host hat (Standard: gcx aktueller Kontext) |
| Welcher gcx-Kontext | --gcx-context <name> (Standard $GCX_CONTEXT); für eine Instanz, die ohne URL benannt ist, aus gcx config list-contexts auswählen |
| An Jira anhängen | --attach-jira ABC-123 (siehe die Umgebungsvariablen unten und die Genehmigungsstufe im Workflow) |
Umgebung
Nichts ist fest codiert: kein Host, keine Adresse. Setzen Sie diese in Ihrem Shell-Profil.
| Variable | Benötigt für | Hinweise |
|---|---|---|
GRAFANA_URL + GRAFANA_TOKEN | statischer Token | der Token wird nur an den Host von GRAFANA_URL gesendet (dann GRAFANA_SERVICE_ACCOUNT_TOKEN, GTOK) |
GCX_CONTEXT | gcx | gcx-Kontext, der erzwungen werden soll, identisch mit --gcx-context |
JIRA_API_TOKEN JIRA_EMAIL JIRA_BASE | nur --attach-jira | alle drei, kein Standardwert |
Auflösungsreihenfolge, identisch für jede Grafana-Fähigkeit: --token; --gcx-context / $GCX_CONTEXT; --grafana-url (der Umgebungs-Token für den Host von $GRAFANA_URL, sonst der gcx-Kontext, der diesen Host bedient, sonst beenden mit der auszuführenden gcx login); gcx aktueller Kontext; der Umgebungs-Token, wenn gcx fehlt. Durch gcx wird dessen eigene OAuth-Aktualisierung angewendet, und dieses Skript liest oder speichert selbst nie eine Anmeldeinformation. Der Resolver wird absichtlich in jeder Fähigkeit dupliziert, sodass jede allein installiert funktioniert.
Workflow
- Besorgen Sie sich die Datenquellen-UID + PromQL aus dem Dashboard (
gcx api /api/dashboards/uid/<uid>, lesen Siepanels[*].targets[*].expr) oder schreiben Sie die Abfrage selbst. - Führen Sie das Skript aus (über das venv python). Farben werden automatisch aus der Grafana-Palette in Serienreihenfolge zugewiesen; die Legende zeigt Mittelwert/Max pro Serie.
- Lesen Sie das PNG zurück, um es vor dem Teilen zu prüfen.
- Optional an Jira anhängen mit
--attach-jira. Es ist ein Tracker-Eintrag, der für das gesamte Team sichtbar ist: Befolgen Sie zuerst die Genehmigungsstufe der Fähigkeitticket-conventions(zeigen Sie die Ticket-ID und das PNG, warten Sie auf ein explizites Ja). Ein fehlgeschlagener Upload wird mit einem Exit-Code ungleich Null beendet.
Beispiel (das kanonische: HAProxy 3.2 vs 2.7 Knotenspeicher)
VENV=${CLAUDE_SKILL_DIR}/.venv/bin/python
SKILL=${CLAUDE_SKILL_DIR}
export JIRA_API_TOKEN=$(zsh -l -c 'echo $JIRA_API_TOKEN') # nur beim Anhängen
export [email protected] JIRA_BASE=https://example.atlassian.net
DS_UID=abc123XYZ # von `gcx datasources list`
$VENV $SKILL/plot_grafana.py \
--datasource-uid $DS_UID \
--expr '(1 - (node_memory_MemAvailable_bytes{instance=~"lb-edge-dc1-(1|4)"} / node_memory_MemTotal_bytes{instance=~"lb-edge-dc1-(1|4)"})) * 100' \
--start now-6h --step 60 \
--title "lb-edge - Knotenspeicher in % verwendet · 3.2 vs 2.7 (dc1, letzte 6h)" \
--ylabel "Speicher in % verwendet" --ymin 0 --ymax 45 \
--rename '{"lb-edge-dc1-1":"HAProxy 3.2.20 (dc1-1)","lb-edge-dc1-4":"HAProxy 2.7.11 (dc1-4, Kontrolle)"}' \
--annotate-max "Neuladen: alter+neuer Worker koexistieren → Knotenspeicher ~2x" \
--grafana-url https://grafana.example.com \
--out ./mem-3.2-vs-2.7.png \
--attach-jira ABC-123
Häufige Fehler
- Diagramm aus einer nicht geprüften Abfrage erstellt → siehe den PromQL-Hinweis oben; eine plausibel falsche Zahl ist die Fehlerart, kein Fehler.
- 401 vom Proxy → bei einem statischen Token gehört dieser nicht zu diesem Host; über gcx ist das Aktualisierungstoken abgelaufen (etwa monatlich), führen Sie
gcx login <context>aus. - System-
python3verwenden →ModuleNotFoundError: matplotlib. Verwenden Sie das venv python. - Leere/eine flache Linie, wo mehrere erwartet werden → der
--expr-Regex hat eine einzelne Serie gefunden; erweitern Sie den Label-Matcher. - Serien unbenannt / alle "Serien" →
--legend-keyzeigt auf ein Label, das die Metrik nicht hat; wählen Sie eines, das sie hat (überprüfen Sie das rohe Abfrageergebnis). :9100(oder ein:port) in Legenden-Namen → wird automatisch aus dem abgeleiteten Seriennamen entfernt, sodass--renameauf den bereinigten Host abzielt (z.B.lb-edge-dc1-1, nichtlb-edge-dc1-1:9100). Keine Notwendigkeit, beide Formen anzugeben.- Relative Zeiten nehmen eine Zahl und eine Einheit, s/m/h/d (
now-90m,now-6h,now-2d). Zusammengesetzte (now-1h30m), Wochen (now-1w) und Rundungen (now/d) werden nicht unterstützt: konvertieren Sie sie (now-90m,now-7d).