PromQL-basierte Benachrichtigungsrichtlinien erstellen (API)

Auf dieser Seite wird beschrieben, wie Sie mit der Cloud Monitoring API eine auf PromQL basierende Benachrichtigungsrichtlinie erstellen. Sie können PromQL-Abfragen in Ihren Benachrichtigungsrichtlinien verwenden, um komplexe Bedingungen mit Funktionen wie Verhältnissen, dynamischen Schwellenwerten und Messwertauswertung zu erstellen.

Allgemeine Informationen finden Sie unter PromQL-basierte Benachrichtigungen – Übersicht.

Wenn Sie in einer Prometheus-Umgebung außerhalb von Cloud Monitoring arbeiten und Prometheus-Benachrichtigungsregeln haben, können Sie die Google Cloud CLI verwenden, um sie zu PromQL-basierten Benachrichtigungsrichtlinien in Monitoring zu migrieren. Weitere Informationen finden Sie unter Benachrichtigungsregeln und Empfänger aus Prometheus migrieren.

Benachrichtigungsrichtlinien mit PromQL-Abfragen erstellen

Benachrichtigungsrichtlinien erstellen Sie mit der Methode alertPolicies.create programmatisch.

Der einzige Unterschied zwischen dem Erstellen von PromQL-basierten Benachrichtigungsrichtlinien und anderen Benachrichtigungsrichtlinien ist, dass Ihr Condition-Typ PrometheusQueryLanguageCondition sein muss. Mit diesem Bedingungstyp können Benachrichtigungsrichtlinien mit PromQL definiert werden.

Im Folgenden sehen Sie eine PromQL-Abfrage für eine Bedingung einer Benachrichtigungsrichtlinie, die einen Messwert aus dem kube-state-Exporter verwendet, um die Anzahl der Neustarts eines Containers in den letzten 30 Minuten zu ermitteln:

rate(kube_pod_container_status_restarts[30m]) * 1800 > 1

Benachrichtigungsrichtlinie aufbauen

Verwenden Sie zum Erstellen einer PromQL-basierten Benachrichtigungsrichtlinie den Bedingungstyp AlertPolicy PrometheusQueryLanguageCondition. PrometheusQueryLanguageCondition hat die folgende Struktur:

{
  "query": string,
  "duration": string,
  "evaluationInterval": string,
  "labels": {string: string},
  "ruleGroup": string,
  "alertRule": string
}

Die Felder PrometheusQueryLanguageCondition haben die folgenden Definitionen:

  • query: Der auszuwertende PromQL-Ausdruck. Entspricht dem Feld expr einer Standard-Prometheus-Benachrichtigungsregel.
  • duration: Gibt an, wie lange bei jeder Auswertung der Abfrage ein true-Wert generiert werden muss, bevor die Bedingung der Benachrichtigungsrichtlinie erfüllt wird. Der Wert muss in Minuten und Sekunden angegeben werden. Beispiel: 600s für eine Dauer von 10 Minuten. Weitere Informationen finden Sie unter Verhalten von messwertbasierten Benachrichtigungsrichtlinien.

  • evaluationInterval: Das Zeitintervall in Sekunden zwischen den PromQL-Auswertungen der Abfrage. Der Standardwert beträgt 30 Sekunden. Wenn die PrometheusQueryLanguageCondition durch die Migration einer Prometheus-Benachrichtigungsregel erstellt wurde, stammt dieser Wert aus der Prometheus-Regelgruppe, die die Prometheus-Benachrichtigungsregel enthielt.

  • labels: Eine optionale Möglichkeit, Labels im Ergebnis des PromQL-Ausdrucks hinzuzufügen oder zu überschreiben.

  • ruleGroup: Wenn die Benachrichtigungsrichtlinie aus einer Prometheus-Konfigurationsdatei migriert wurde, enthält dieses Feld den Wert des Felds name aus der Regelgruppe in der Prometheus-Konfigurationsdatei. Dieses Feld ist nicht erforderlich, wenn Sie eine PromQL-Benachrichtigungsrichtlinie in der Cloud Monitoring API erstellen.

  • alertRule: Wenn die Benachrichtigungsrichtlinie aus einer Prometheus-Konfigurationsdatei migriert wurde, enthält dieses Feld den Wert des Felds alert aus der Benachrichtigungsregel in der Prometheus-Konfigurationsdatei. Dieses Feld ist nicht erforderlich, wenn Sie eine PromQL-Benachrichtigungsrichtlinie in der Cloud Monitoring API erstellen.

In der folgenden Bedingung wird beispielsweise eine PromQL-Abfrage verwendet, um die Anzahl der Neustarts eines Containers in den letzten 30 Minuten zu ermitteln:

"conditionPrometheusQueryLanguage": {
  "query": "rate(kube_pod_container_status_restarts[30m]) * 1800 > 1",
  "duration": "600s",
  evaluationInterval: "60s",
  "alertRule": "ContainerRestartCount",
  "labels": {
    "action_required":"true",
    "severity":"critical/warning/info"}
}

Verwenden Sie diese Struktur als Wert des Felds conditionPrometheusQueryLanguage in einer Bedingung, die wiederum in eine Struktur für Benachrichtigungsrichtlinien eingebettet ist. Weitere Informationen zu diesen Strukturen finden Sie unter AlertPolicy.

Das folgende Beispiel zeigt eine vollständige Richtlinie mit einer Bedingung PrometheusQueryLanguageCondition in JSON:

{
  "displayName": "Container Restarts",
  "documentation": {
    "content": "Pod ${resource.label.namespace_name}/${resource.label.pod_name} has restarted more than once during the last 30 minutes.",
    "mimeType": "text/markdown",
    "subject": "Container ${resource.label.container_name} in Pod ${resource.label.namespace_name}/${resource.label.pod_name} has restarted more than once during the last 30 minutes."
  },
  "userLabels": {},
  "conditions": [
    {
      "displayName": "Container has restarted",
      "conditionPrometheusQueryLanguage": {
        "query": "rate(kubernetes_io:container_restart_count[30m]) * 1800",
        "duration": "600s",
        evaluationInterval: "60s",
        "alertRule": "ContainerRestart",
        "labels": {
          "action_required":"true",
          "severity":"critical/warning/info"}
      }
    }
  ],
  "combiner": "OR",
  "enabled": true
}

Benachrichtigungsrichtlinie erstellen

Um die Benachrichtigungsrichtlinie zu erstellen, fügen Sie die JSON-Datei der Benachrichtigungsrichtlinie in eine Datei mit dem Namen POLICY_NAME.json ein und führen Sie dann den folgenden Befehl aus:

curl -d @POLICY_NAME.json -H "Authorization: Bearer $TOKEN"
-H 'Content-Type: application/json'
-X POST https://monitoring.googleapis.com/v3/projects/${PROJECT}/alertPolicies

Weitere Informationen zur Monitoring API für Benachrichtigungsrichtlinien finden Sie unter Benachrichtigungsrichtlinien über API verwalten.

Weitere Informationen zur Verwendung von curl finden Sie unter curl aufrufen.

Prüfung auf Vorhandensein von Messwerten deaktivieren

Wenn Sie eine PromQL-basierte Benachrichtigungsrichtlinie erstellen, wird von Google Cloudeine Validierung durchgeführt, um sicherzustellen, dass die in der Bedingung referenzierten Messwerte bereits in Monitoring vorhanden sind. Sie können diese Validierung jedoch überschreiben, wenn Sie eine Benachrichtigungsrichtlinie erstellen müssen, bevor die Messwerte vorhanden sind. Das kann beispielsweise sinnvoll sein, wenn Sie mithilfe von Automatisierung neue Projekte erstellen, die mit einem Standardsatz vordefinierter Benachrichtigungsrichtlinien ausgestattet sind. Wenn Sie die Validierung nicht deaktivieren, schlägt die Erstellung der Benachrichtigungsrichtlinie fehl, bis die zugrunde liegenden Messwerte erstellt wurden.

Wenn Sie die Prüfung auf das Vorhandensein von Messwerten deaktivieren möchten, fügen Sie das Feld "disableMetricValidation": true zu Ihrem PrometheusQueryLanguageCondition hinzu:

{
  "query": string,
  "duration": string,
  "evaluationInterval": string,
  "labels": {string: string},
  "ruleGroup": string,
  "disableMetricValidation": true,
  "alertRule": string
}

Wenn in der Bedingung einer Benachrichtigungsrichtlinie auf einen Messwert verwiesen wird, der nicht vorhanden ist, wird die Bedingung trotzdem gemäß dem zugehörigen Auswertungsintervall ausgeführt. Das Abfrageergebnis ist jedoch immer leer. Nachdem der zugrunde liegende Messwert vorhanden ist, gibt die Abfrage Daten zurück.

Terraform verwenden

Eine Anleitung zum Konfigurieren von PromQL-basierten Benachrichtigungsrichtlinien mit Terraform finden Sie im Abschnitt condition_prometheus_query_language der google_monitoring_alert_policy-Terraform-Registry.

Allgemeine Informationen zur Verwendung von Google Cloud mit Terraform finden Sie unter Terraform mit Google Cloud.

curl aufrufen

Jeder curl-Aufruf enthält eine Reihe von Argumenten, gefolgt von der URL einer API-Ressource. Zu den gängigen Argumenten gehören eine Google Cloud Projekt-ID und ein Authentifizierungstoken. Diese Werte werden hier durch die Umgebungsvariablen PROJECT_ID und TOKEN dargestellt.

Möglicherweise müssen Sie auch andere Argumente angeben, um beispielsweise den Typ der HTTP-Anfrage anzugeben (z. B. -X DELETE). Die Standardanfrage ist GET. Daher wird sie in den Beispielen nicht angegeben.

Jeder curl-Aufruf hat diese allgemeine Struktur:

curl --http1.1 --header "Authorization: Bearer ${TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>

Wenn Sie curl verwenden möchten, müssen Sie Ihre Projekt-ID und einen Zugriffstoken angeben. Um Tippfehler und Fehler zu vermeiden, können Sie diese in Umgebungsvariablen einfügen, indem Sie sie auf diese Weise an curl übergeben.

So legen Sie diese Variablen fest:

  1. Erstellen Sie eine Umgebungsvariable, die die ID Ihres Scoping-Projekts eines Messwertbereichs enthält. Mit diesen Schritten wird die Variable PROJECT_ID aufgerufen:

    PROJECT_ID=a-sample-project

  2. Authentifizieren Sie sich in der Google Cloud CLI:

    gcloud auth login

  3. Optional. Damit Sie nicht bei jedem gcloud-Befehl Ihre Projekt-ID angeben müssen, legen Sie Ihre Projekt-ID mithilfe der gcloud CLI als Standard fest:

    gcloud config set project ${PROJECT_ID}

  4. Erstellen Sie ein Autorisierungstoken und erfassen Sie es in einer Umgebungsvariablen. Mit diesen Schritten wird die Variable TOKEN aufgerufen:

    TOKEN=`gcloud auth print-access-token`

    Sie müssen das Zugriffstoken regelmäßig aktualisieren. Wenn zuvor funktionierende Befehle plötzlich melden, dass Sie nicht authentifiziert sind, führen Sie diesen Befehl noch einmal aus.

  5. Bestätigen Sie, dass Sie ein Zugriffstoken erhalten haben. Geben Sie dazu die Variable TOKEN zurück:

    echo ${TOKEN}
ya29.GluiBj8o....