promtool-Befehle: Prometheus-Regeln prüfen und testen

promtool ist das offizielle Werkzeug zur Arbeit mit Prometheus-Konfiguration und Abfragen. Es prüft Regeldateien vor dem Ausrollen, führt Abfragen gegen einen laufenden Server aus und testet Regeln mit festen Eingabedaten. Diese Referenz zeigt die wichtigsten Aufrufe.

Konfiguration prüfen

# Prometheus-Gesamtkonfiguration validieren
promtool check config /etc/prometheus/prometheus.yml

# Nur Regeldateien prüfen (Syntax und Ausdrücke)
promtool check rules /etc/prometheus/rules/*.yml

# Dienstdefinitionen für Service Discovery prüfen
promtool check service-discovery --config.file=/etc/prometheus/prometheus.yml

Immer vor dem Neustart prüfen. Ein Syntaxfehler in einer Regeldatei führt dazu, dass Prometheus die gesamte Konfiguration nicht lädt – die Überwachung steht dann, während man den Fehler sucht. Der Aufruf gehört deshalb in die Pipeline, nicht erst ins Deployment.

Abfragen ausführen

# Momentane Abfrage gegen einen laufenden Prometheus
promtool query instant http://localhost:9090 'up == 0'

# Bereichsabfrage (Start, Ende, Schrittweite)
promtool query range --start=2026-09-26T08:00:00Z --end=2026-09-26T09:00:00Z \
  --step=1m http://localhost:9090 'rate(http_requests_total[5m])'

# Abfragen aus einer Datei (eine pro Zeile)
promtool query instant http://localhost:9090 -f abfragen.txt

Regeln testen

Das ist die stärkste Funktion: Regeln lassen sich mit vorgegebenen Zeitreihen prüfen, ohne einen Server zu betreiben.

# regeln.yml
groups:
  - name: beispiel
    rules:
      - alert: InstanzNichtErreichbar
        expr: up == 0
        for: 5m
        labels:
          severity: critical

# regeln_test.yml
rule_files:
  - regeln.yml
evaluation_interval: 1m
tests:
  - interval: 1m
    input_series:
      - series: 'up{job="node",instance="web01:9100"}'
        values: '1 1 0 0 0 0 0 0'
    alert_rule_test:
      - eval_time: 7m
        alertname: InstanzNichtErreichbar
        exp_alerts:
          - exp_labels:
              severity: critical
              job: node
              instance: web01:9100
            exp_annotations: {}

promtool test rules regeln_test.yml

Mit values: '1 1 0 0 0 ...' werden Verläufe als Aneinanderreihung von Werten beschrieben; Wiederholungen lassen sich abkürzen (1x3 für dreimal die 1). Der Test prüft, ob der Alarm zum erwarteten Zeitpunkt mit den erwarteten Labels auslöst – genau das, was bei for:-Verzögerungen sonst nur im Betrieb auffällt.

Zeitreihen und Metriken erkunden

# Alle Metriknamen auflisten
promtool query instant http://localhost:9090 '{__name__=~".+"}' | head

# Label-Werte
promtool query instant http://localhost:9090 'count by (job) (up)'

# Daten in ein OpenMetrics-Format wandeln
promtool tsdb create-blocks-from openmetrics eingabe.txt /var/lib/prometheus/data/

TSDB-Werkzeuge

# Zustand der lokalen Zeitreihendatenbank
promtool tsdb analyze /var/lib/prometheus/data
promtool tsdb list /var/lib/prometheus/data

# Statistik zu Kardinalität pro Metrik
promtool tsdb analyze /var/lib/prometheus/data --limit=20

# Blöcke verdichten und aufräumen
promtool tsdb create-blocks-from ...     # Import
# Für die Rechtevergabe:
promtool tsdb dump /var/lib/prometheus/data | head

tsdb analyze ist das Werkzeug der Wahl bei Speicherproblemen: Es zeigt, welche Metriken und Labels die meisten Zeitreihen erzeugen. Meist sind es wenige Label-Kombinationen mit hoher Kardinalität – etwa Benutzer-IDs oder Anfrage-IDs in Labels, die dort nichts zu suchen haben.

Checks für die CI

# In einer Pipeline
promtool check rules rules/*.yml || exit 1
promtool test rules tests/*_test.yml || exit 1

Praxis-Tipps

Regeln immer testen: Ein Alarm, der nie auslöst, weil der Ausdruck falsch ist, ist gefährlicher als kein Alarm – er erzeugt falsche Sicherheit.
for: erfordert Zeit im Test: Ohne mehrere Evaluierungsintervalle im Eingabeverlauf kann ein Alarm mit Verzögerung nicht auslösen. Der Test braucht also mehr Werte als die Wartezeit in Minuten.
Kardinalität im Blick behalten: tsdb analyze regelmäßig laufen lassen, bevor der Speicher voll ist.
Nicht gegen Produktion testen: promtool test rules läuft lokal mit Eingabedaten – das ist schneller, reproduzierbar und ohne Risiko.