Recording Rules für Observability in Grafana verwenden

Recording Rules ermöglichen es Ihnen, häufig benötigte oder rechenintensive Ausdrücke vorab zu berechnen und deren Ergebnis als neuen Satz von Zeitreihen zu speichern.

Das Abfragen des vorab berechneten Ergebnisses ist dadurch häufig deutlich schneller als die erneute Ausführung des ursprünglichen Ausdrucks bei jeder Verwendung. Dies ist insbesondere für Dashboards nützlich, die bei jeder Aktualisierung wiederholt denselben Ausdruck abfragen müssen.

Recording Rules und Alerting Rules sind syntaktisch identisch. Daher können beide Typen in dieselbe Konfigurationsdatei geschrieben werden. Recording- und Alerting-Regeln existieren innerhalb einer Regelgruppe. Die Regeln innerhalb einer Gruppe werden sequenziell in einem regelmäßigen Intervall mit derselben Auswertungszeit ausgeführt.

Um die folgenden API-Befehle auszuführen, benötigen Sie Ihre STACKIT-Kennungen ($PROJECT_ID, $INSTANCE_ID) sowie selbst definierte Namen für Ihre Regeln ($GROUP_NAME, $RECORD_NAME).

Anleitungen, wo Sie Ihre STACKIT-IDs finden, sowie zur Verwendung des stackit curl-Wrappers für die Authentifizierung lesen Sie unter Interaktion mit der Observability API.

Gemeinsame Parameter

Gemeinsame Parameter für Recording Rules

• record (string): Der Name der auszugebenden Zeitreihe. Dies muss ein gültiger Metrikname sein.
• expr (string): Der auszuwertende PromQL-Ausdruck. Bei jedem Auswertungszyklus wird dieser zum aktuellen Zeitpunkt ausgewertet und das Ergebnis als neuer Satz von Zeitreihen mit dem durch record angegebenen Metriknamen gespeichert.
• labels ([ labelname: label value ]): Labels, die vor dem Speichern des Ergebnisses hinzugefügt oder überschrieben werden.

Gemeinsame Parameter für Recording-Gruppen

• name (string): Der Name der Gruppe. Dieser muss innerhalb einer Datei eindeutig sein.
• interval (duration | default = global.evaluation_interval): Gibt an, wie häufig die Regeln innerhalb der Gruppe ausgewertet werden.
• limit (int | default = 0): Begrenzt die Anzahl der Alarme, die eine Alerting Rule, sowie die Anzahl der Zeitreihen, die eine Recording Rule erzeugen kann. 0 bedeutet keine Begrenzung.
• rules: Eine Liste der spezifischen Regeln.

Metriknamen und Labels

Jede Zeitreihe wird eindeutig durch ihren Metriknamen und optionale Schlüssel-Wert-Paare, sogenannte Labels, identifiziert.

Metriknamen

• Beschreiben die allgemeine Eigenschaft eines Systems, die gemessen wird (z. B. http_requests_total – die Gesamtanzahl der empfangenen HTTP-Anfragen).
• Metriknamen dürfen ASCII-Buchstaben, Ziffern, Unterstriche und Doppelpunkte enthalten. Sie müssen dem regulären Ausdruck [a-zA-Z_:][a-zA-Z0-9_:]* entsprechen.
• Hinweis: Doppelpunkte sind für benutzerdefinierte Recording Rules reserviert. Sie sollten nicht von Exportern oder direkter Instrumentierung verwendet werden.

Metrik-Labels

• Ermöglichen das dimensionale Datenmodell von Prometheus, um jede beliebige Kombination von Labels für denselben Metriknamen zu identifizieren.
• Sie beschreiben eine konkrete dimensionale Ausprägung dieser Metrik (z. B. alle HTTP-Anfragen mit der Methode POST an den Handler /api/tracks).
• Jede Änderung eines Label-Werts – einschließlich des Hinzufügens oder Entfernens von Labels – erzeugt eine neue Zeitreihe.
• Labelnamen dürfen ASCII-Buchstaben, Ziffern und Unterstriche enthalten. Sie müssen dem regulären Ausdruck [a-zA-Z_][a-zA-Z0-9_]* entsprechen.
• Labelnamen, die mit __ (zwei Unterstriche) beginnen, sind für interne Zwecke reserviert.
• Label-Werte dürfen beliebige Unicode-Zeichen enthalten. Labels mit einem leeren Label-Wert gelten als gleichwertig zu nicht vorhandenen Labels.

Weitere Details finden Sie in den Best Practices für die Benennung von Prometheus-Metriken.

Beispiele

Beispiel für eine Rules-Datei

Eine typische YAML-Definition für eine Recording Rule erfordert die folgende Struktur:

groups:
  - name: <Der Gruppenname der Recording Rule>
    rules:
      - record: <Der Name der Zeitreihe>
        expr: <Der auszuwertende PromQL-Ausdruck>

Ein einfaches Beispiel für eine Rules-Datei (rules.yaml) wäre:

groups:
  - name: http_resources
    interval: 5m
    rules:
      - record: code:prometheus_http_requests_total:sum
        expr: sum by (code) (prometheus_http_requests_total)
  - name: node_resources
    rules:
      - record: node_memory_MemFree_percent
        expr: 100 - (100 * node_memory_MemFree_bytes / node_memory_MemTotal_bytes)
      - record: node_filesystem_free_percent
        expr: 100 * node_filesystem_free_bytes{mountpoint="/"} / node_filesystem_size_bytes{mountpoint="/"}
  - name: group_name
    rules:
      - record: job:prometheus_http_requests_total:rate5m
        expr: sum without(instance, method, controller, status_code)(rate(prometheus_http_requests_total[5m]))
        labels:
          test: test

Verwaltung von Recording Rules über die API

Sie können Ihre Recording Rules direkt über die STACKIT Observability API mit dem stackit curl-Wrapper verwalten. Die Variablen $GROUP_NAME und $RECORD_NAME in den folgenden Befehlen sind benutzerdefinierte Namen, die Sie für Ihre Ressourcen festlegen.

Recording-Gruppe erstellen

Eine Recording-Gruppe enthält eine oder mehrere Recording Rules und dient dazu, Regeln mit zusammengehörigen Metriken zu bündeln.

stackit curl -X POST "[https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/$GROUP_NAME/records](https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/$GROUP_NAME/records)" \
  -H "Content-Type: application/json" \
  --data '{
  "record": "string",
  "expr": "string",
  "labels": {}
}'

Recording Rule erstellen

Um Recording Rules unabhängig von der Gruppe zu definieren oder Regeln zu einer bestehenden Gruppe hinzuzufügen, verwenden Sie den folgenden PUT-Aufruf:

stackit curl -X PUT "[https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/$GROUP_NAME/records/$RECORD_NAME](https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/$GROUP_NAME/records/$RECORD_NAME)" \
  -H "Content-Type: application/json" \
  --data '{
    "expr": "freezer_room_temperature{freezer='\''lidl_hn_neckarsulmerstr_f121'\''} - freezer_temperature{freezer='\''lidl_hn_neckarsulmerstr_f121'\''}",
    "labels": {}
}'

Recording Rule aktualisieren

Eine oder mehrere Recording Rules innerhalb einer Gruppe können mit einer PATCH-Anfrage aktualisiert werden:

stackit curl -X PATCH "[https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/$GROUP_NAME/records](https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/$GROUP_NAME/records)" \
  -H "Content-Type: application/json" \
  --data '[
  {
    "record": "string",
    "expr": "string",
    "labels": {}
  },
  {
    "record": "freezerdifftemp",
    "expr": "freezer_room_temperature{freezer='\''lidl_hn_neckarsulmerstr_f121'\''} - freezer_temperature{freezer='\''lidl_hn_neckarsulmerstr_f121'\''}",
    "labels": {
      "device": "freezer"
    }
  }
]'

Recording-Gruppe auslesen

Zur Überprüfung Ihrer Konfiguration können Sie alle Regeln innerhalb einer bestimmten Recording-Gruppe abrufen:

stackit curl -X GET "[https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/$GROUP_NAME/records](https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/$GROUP_NAME/records)"

Einzelne Recording Rule auslesen

Um die Details einer einzelnen, spezifischen Recording Rule anzuzeigen:

stackit curl -X GET "[https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/$GROUP_NAME/records/$RECORD_NAME](https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/$GROUP_NAME/records/$RECORD_NAME)"

Recording-Gruppe löschen

Um eine gesamte Recording-Gruppe und alle zugehörigen Regeln zu löschen:

stackit curl -X DELETE "[https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/$GROUP_NAME/records](https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/$GROUP_NAME/records)"

Einzelne Recording Rule löschen

Um nur eine spezifische Recording Rule aus einer Gruppe zu löschen:

stackit curl -X DELETE "[https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/$GROUP_NAME/records/$RECORD_NAME](https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertgroups/$GROUP_NAME/records/$RECORD_NAME)"

Syntax-Check von Recording Rules

Um schnell zu prüfen, ob eine Rules-Datei syntaktisch korrekt ist, ohne einen Prometheus-Server zu starten, können Sie das Kommandozeilen-Tool promtool von Prometheus verwenden:

promtool check rules /path/to/example.rules.yml

Verwendung von Recording Rules in Grafana

In Grafana sehen Sie im Metrics Browser zusätzliche Metriken, die aus Ihren Recording Rules erzeugt wurden. Der Name der neuen Metrik entspricht direkt dem Wert, den Sie im Feld record festgelegt haben.

Referenzen

• STACKIT Observability Alert Records API-Spezifikation
• Prometheus-Dokumentation: Recording Rules
• Prometheus-Dokumentation: Metrik-Namen und Labels
• Prometheus-Dokumentation: Best Practices für die Benennung
• So optimieren Sie PromQL- und MetricsQL-Abfragen