Verwendung von Recording Rules in Grafana

Einführung

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.
Der API-Endpunkt hierfür lautet:
https://argus.api.eu01.stackit.cloud/v1/projects/[project_id]/instances/[instance_id]/alertgroups/[alert_group]/records

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.
Die Namen von Recording Rules müssen gültige Metriknamen sein.

Gemeinsame Parameter

Gemeinsame Parameter für Recording Rules

record: string
Der Name der auszugebenden Zeitreihe. 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: labelvalue ]
Labels, die vor dem Speichern des Ergebnisses hinzugefügt oder überschrieben werden.

Gemeinsame Parameter für Recording-Gruppen

name: string
Der Name der Gruppe. 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:
[ - rule… ]

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 und 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).
Die Abfragesprache erlaubt das Filtern und Aggregieren basierend auf diesen Dimensionen.
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.

Best Practices für die Benennung von Metriken finden Sie hier:
https://prometheus.io/docs/practices/naming/

Beispiele

Beispiel für eine Rules-Datei

Folgendes ist erforderlich:

groups:
 - name: <Der name der Recording Regel>
 rules:
 - record: <The name of the time series>
 expr: <The PromQL expression to evaluate>

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

groups:
- name: http_ressources
 interval: 5m
 rules:
 - record: code:prometheus_http_requests_total:sum
 expr: sum by (code) (prometheus_http_requests_total)
- name: node_ressources
 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

Recording-Gruppe erstellen

Eine Recording-Gruppe enthält eine oder mehrere Recording Rules und dient dazu, Regeln mit zusammengehörigen Metriken zu bündeln.
Recording Rules können auch innerhalb einer Alert Group definiert werden.

curl -X POST --location 'https://argus.api.eu01.stackit.cloud/v1/projects/{projectId}/instances/{instanceId}/alertgroups/{groupName}/records' \
--header 'Authorization: Bearer <bearer-token_from_stackit-portal_access-token>' \
--header 'Content-Type: text/plain' \
--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 Aufruf.

curl -X PUT --location 'https://argus.api.eu01.stackit.cloud/v1/projects/{projectId}/instances/{instanceId}/alertgroups/{groupName}/records/{alertRecord}' \
--header 'Authorization: Bearer <bearer-token_from_stackit-portal_access-token>' \
--header 'Content-Type: text/plain' \
--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 können mit dem folgenden API-Aufruf aktualisiert werden.

curl -X PATCH --location 'https://argus.api.eu01.stackit.cloud/v1/projects/{projectId}/instances/{instanceId}/alertgroups/{groupName}/records' \
--header 'Authorization: Bearer <bearer-token_from_stackit-portal_access-token>' \
--header 'Content-Type: text/plain' \
--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 können Sie eine Recording-Gruppe auslesen:

curl -X GET --location 'https://argus.api.eu01.stackit.cloud/v1/projects/{projectId}/instances/{instanceId}/alertgroups/{groupName}/records' \
--header 'Authorization: Bearer <bearer-token_from_stackit-portal_access-token>'

Recording Rule auslesen

Eine spezifische Recording Rule anzeigen:

curl -X GET --location 'https://argus.api.eu01.stackit.cloud/v1/projects/{projectId}/instances/{instanceId}/alertgroups/{groupName}/records/{alertRecord}' \
--header 'Authorization: Bearer <bearer-token_from_stackit-portal_access-token>'

Gruppe von Recording Rules löschen

Das Löschen einer Recording-Gruppe ist ebenfalls möglich. Der folgende Aufruf zeigt, wie dies funktioniert:

curl -X DELETE --location --request DELETE 'https://argus.api.eu01.stackit.cloud/v1/projects/{projectId}/instances/{instanceId}/alertgroups/{groupName}/records' \
--header 'Authorization: Bearer <bearer-token_from_stackit-portal_access-token>'

Einzelne Recording Rule löschen

Das Löschen einer einzelnen Recording Rule sieht wie folgt aus:

curl -X DELETE --location --request DELETE 'https://argus.api.eu01.stackit.cloud/v1/projects/{projectId}/instances/{instanceId}/alertgroups/{groupName}/records/{alertRecord}' \
--header 'Authorization: Bearer <bearer-token_from_stackit-portal_access-token>'

Syntax-check 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