Dynamische Grafana Annotations erstellen – alle wichtigen Zeiten automatisch markieren!

Annotations in Grafana sind wie diese kleinen Post-its, die du an den Rand deines Monitors pinnen würdest: „Hier ist gerade etwas Spannendes passiert!“ Nur dass du sie dir nicht mühsam von Hand anlegen musst. Und das Beste? Sie kommen automatisch genau dann, wenn du sie brauchst.

Hand aufs Herz: Wer hat schon Lust, mühselig Start- und Endzeitpunkte per Hand in Grafana einzutragen? Gerade in modernen Monitoring-Setups mit Infrastructure as Code (IaC) willst du lieber automatisch sehen, wann was los war – sei es ein Datenleck in Prometheus oder ein laufendes Deployment. Genau hier sind dynamische Annotations Gold wert!

In diesem Blogpost zeige ich dir, wie du mit einem einfachen Bash-Script dynamisch und automatisiert Annotations in Grafana auf deinen Dashboards setzt – inklusive Start- und Endzeiten. So bleibt dein Dashboard nicht nur sauber, sondern auch super informativ!

Warum solltest du dynamische Annotations in Grafana nutzen?

In der Welt des modernen Monitorings ist Automatisierung das A und O. Infrastruktur wird als Code gemanagt, Deployments laufen automatisch, und trotzdem willst du im Ernstfall schnell nachvollziehen, was wann schiefgelaufen ist.

Annotations helfen dir dabei, indem sie wichtige Ereignisse direkt auf den Dashboards markieren – mit Text, Tags und Zeitpunkten. So siehst du auf einen Blick, wann ein Vorfall angefangen hat und wann er vorbei war.

Das Sahnehäubchen: Über Grafanas API kannst du diese digitalen Post-its programmatisch anlegen und aktualisieren. Dadurch sparst du dir manuelle Klick-Orgien, vermeidest Fehler – und behältst auch bei komplexen Mehrfach-Deployments stets den Überblick.

Was brauchst du für dein dynamisches Annotation-Skript?

Damit die Magie funktioniert, solltest du folgende Zutaten bereitstellen:

• Grafana API Key: Ein API-Token, mit dem dein Script sich authentifiziert. Wie du das erstellst? Hier gibt’s eine ausführliche Anleitung.
• Dashboard UIDs: Die eindeutigen IDs deiner Dashboards, auf denen du Annotations setzen möchtest.
• Werkzeuge: Curl für API-Anfragen und jq, um JSON elegant zu parsen.

Klingt nach viel Zauberei? Keine Sorge, ich führe dich Schritt für Schritt durch das Script.

So funktioniert das Script: Schritt für Schritt zur automatischen Annotation

1. Die Basics definieren

Zuerst legst du die wichtigsten Parameter fest: Die URL zu deinem Grafana-Server, deinen API-Key, die Dashboard-UIDs, Tags, den Text der Annotation und natürlich den Startzeitpunkt in Millisekunden.

GRAFANA_URL="http://grafana:3000"
API_TOKEN="<Dein_API_Key>"
ANNOTATION_IDS=()
DASHBOARD_UIDS=("erstes_dashbord" "zweites_dashbord")
TAGS='["script","automation"]'
TEXT="Erstellt mit einem Bashscript"
TIME_START=$(date +%s%3N)  # aktuelle Zeit in ms

Die Variable ANNOTATION_IDS dient dazu, die IDs aller erzeugten Annotations zu sammeln – praktisch, wenn du später die Endzeit nachtragen möchtest.

2. Alle Panel-IDs aus dem Dashboard auslesen

Ein Dashboard besteht aus Panels, und jede Annotation gehört zu einem bestimmten Panel. Mit der Grafana-API holst du dir die Dashboard-Struktur und extrahierst alle Panel-IDs – auch die in verschachtelten Gruppen oder Zeilen.

response=$(curl -k "$GRAFANA_URL/apis/dashboard.grafana.app/v1beta1/namespaces/default/dashboards/$DASHBOARD_UID" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_TOKEN" 2>/dev/null)

response_fixed=$(echo "$response" | sed -e 's/\\\\/\\/g' -e 's/\\\([^"\\/bfnrtu]\)/\1/g')

PANEL_IDS=$(echo "$response_fixed" | jq '
def find_panels(panels):
    panels[]
    | if .type == "row" and (.panels | type == "array") 
        then find_panels(.panels)
        else .
    end;
find_panels(.spec.panels) | select(.type != "row") | .id
')

3. Für jedes Panel eine Annotation anlegen

Jetzt geht’s ans Eingemachte: Für jede gesammelte Panel-ID legst du eine Annotation an, die den Startzeitpunkt, Tags und den Text enthält.

for PANEL_ID in $PANEL_IDS; do
    response=$(curl -k -X POST "$GRAFANA_URL/api/annotations" \
        -H "Accept: application/json" \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer $API_TOKEN" \
        -d '{
            "dashboardUID": "'"$DASHBOARD_UID"'",
            "panelId": '"$PANEL_ID"',
            "time": '"$TIME_START"',
            "tags": '"$TAGS"',
            "text": "'"$TEXT"'"
        }')
    ANNOTATION_ID=$(echo "$response" | jq -r '.id')
    ANNOTATION_IDS+=("$ANNOTATION_ID")
done

Mit der gespeicherten ANNOTATION_ID kannst du die Annotation später ganz easy noch anpassen.

4. Hier läuft deine Automation

An dieser Stelle baust du dein eigenes Automations- oder Deployment-Skript ein – sei es ein Kubernetes-Rollout, API-Tests oder andere Ereignisse, die du überwachen möchtest.

5. Endzeit in alle Annotationen eintragen

Wenn dein Vorgang fertig ist, trägst du den Endzeitpunkt in alle Annotations ein, damit Grafana das Ereignis als Zeitspanne visualisieren kann.

TIME_END=$(date +%s%3N)
for ANNOTATION_ID in ${ANNOTATION_IDS[@]}; do
    curl -k -X PUT "$GRAFANA_URL/api/annotations/$ANNOTATION_ID" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $API_TOKEN" \
    -d '{
        "timeEnd": '"$TIME_END"',
        "tags": '"$TAGS"',
        "text": "'"$TEXT"'"
    }'
done

So siehst du sofort auf dem Dashboard, wie lange dein Ereignis gedauert hat – ohne lästige manuelle Nacharbeit.

Das vollständige Script zum Nachbauen

GRAFANA_URL="http://grafana:3000"
API_TOKEN="<Dein_API_Key>"
ANNOTATION_IDS=()
DASHBOARD_UIDS=("erstes_dashbord")  # mehrere: ("erstes_dashbord" "zweites_dashbord")
TAGS='["script","automation"]'
TEXT="Erstellt mit einem Bashscript"
TIME_START=$(date +%s%3N)   

for DASHBOARD_UID in $DASHBOARD_UIDS; do
    response=$(curl -k "$GRAFANA_URL/apis/dashboard.grafana.app/v1beta1/namespaces/default/dashboards/$DASHBOARD_UID" \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $API_TOKEN" 2>/dev/null)

    response_fixed=$(echo "$response" | sed -e 's/\\\\/\\/g' -e 's/\\\([^"\\/bfnrtu]\)/\1/g')

    PANEL_IDS=$(echo "$response_fixed" | jq '
    def find_panels(panels):
        panels[]
        | if .type == "row" and (.panels | type == "array") 
            then find_panels(.panels)
            else .
        end;
    find_panels(.spec.panels) | select(.type != "row") | .id
    ')

    for PANEL_ID in $PANEL_IDS; do
        response=$(curl -k -X POST "$GRAFANA_URL/api/annotations" \
          -H "Accept: application/json" \
          -H "Content-Type: application/json" \
          -H "Authorization: Bearer $API_TOKEN" \
          -d '{
              "dashboardUID": "'"$DASHBOARD_UID"'",
              "panelId": '"$PANEL_ID"',
              "time": '"$TIME_START"',
              "tags": '"$TAGS"',
              "text": "'"$TEXT"'"
          }')
        ANNOTATION_ID=$(echo "$response" | jq -r '.id')
        ANNOTATION_IDS+=("$ANNOTATION_ID")
    done
done

# <Dein Automations-Schritt hier>

TIME_END=$(date +%s%3N)
for ANNOTATION_ID in ${ANNOTATION_IDS[@]}; do
    curl -k -X PUT "$GRAFANA_URL/api/annotations/$ANNOTATION_ID" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $API_TOKEN" \
    -d '{
        "timeEnd": '"$TIME_END"',
        "tags": '"$TAGS"',
        "text": "'"$TEXT"'"
    }'
done

Fazit – Mehr Überblick, weniger Fehler

Mit diesem Script automatisierst du das Setzen und Aktualisieren von Grafana-Annotations und sorgst damit für echte Ordnung auf deinen Dashboards. Besonders bei IaC-Deployments oder wenn Fehler schnell sichtbar sein müssen, sparst du so extrem viel Zeit und Nerven.

Und das Schönste: Das Prinzip ist flexibel und lässt sich einfach an andere Scripting- oder CI/CD-Umgebungen anpassen – damit deine Dashboards immer aktuell bleiben.