PromQL für Cloud Monitoring

In diesem Dokument wird die Verwendung der Prometheus Query Language (PromQL) in Cloud Monitoring beschrieben. PromQL ist eine Alternative zur menügesteuerten Oberfläche des Metrics Explorer zum Erstellen von Diagrammen und Dashboards.

Sie können PromQL verwenden, um Cloud Monitoring-Daten aus den folgenden Quellen abzufragen und grafisch darzustellen:

Sie können auch Tools wie Grafana verwenden, um in Cloud Monitoring aufgenommene Messwertdaten in Diagrammen darzustellen. Zu den verfügbaren Messwerten gehören Messwerte aus dem Managed Service for Prometheus und Cloud Monitoring-Messwerte, die in den Messwertlisten dokumentiert sind. Informationen zum Einrichten von Grafana und anderen Tools, die auf der Prometheus API basieren, finden Sie in der Dokumentation zu Managed Service for Prometheus unter Grafana.

Sie können auch Ihre Grafana-Dashboards in Cloud Monitoring importieren.

Cloud Monitoring-Messwerte mit PromQL abfragen

Cloud Monitoring-Messwerte können mit der UTF-8-Spezifikation für PromQL abgefragt werden. UTF-8-Messwertnamen müssen in Anführungszeichen gesetzt und in die geschweiften Klammern verschoben werden. Labelnamen müssen auch in Anführungszeichen gesetzt werden, wenn sie Zeichen enthalten, die mit der alten Version nicht kompatibel sind. Für den Cloud Monitoring-Messwert kubernetes.io/container/cpu/limit_utilization sind die folgenden Abfragen gleichwertig:

  • {"kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}
  • {__name__="kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}.
  • {"__name__"="kubernetes.io/container/cpu/limit_utilization", "pod_name"="foo"}.

Cloud Monitoring-Verteilungsmesswerte können wie Prometheus-Histogramme abgefragt werden, wobei das Suffix _count, _sum oder _bucket an den Messwertnamen angehängt wird.

Sie können in PromQL Metadatenlabels wie jedes andere Label verwenden, wobei wie bei Messwertnamen auch Metadatenlabels von PromQL kompatibel sein müssen. Die Syntax für den Verweis auf ein Metadatensystemlabel vom Typ version lautet metadata_system_version und die Syntax für Metadatennutzerlabel vom Typ version lautet metadata_user_version. Korrekt formulierte PromQL-Abfragen mit Metadatenlabels können so aussehen:

  • {"compute.googleapis.com/instance/cpu/utilization", monitored_resource="gce_instance",metadata_user_env="prod"}
  • sum("compute.googleapis.com/instance/cpu/utilization") by (metadata_system_region)
  • sum("compute.googleapis.com/instance/cpu/utilization") by (metadata_user_env)
  • {"compute.googleapis.com/instance/uptime_total", "metadata_user_i-love.special/chars"="yes"}
  • sum("compute.googleapis.com/instance/uptime_total") by ("metadata_user_i-love.special/chars")

Wenn Ihr Metadatenlabelschlüssel andere Sonderzeichen als das Zeichen _ enthält, müssen Sie den Labelschlüssel gemäß der UTF‑8-Spezifikation von PromQL in doppelte Anführungszeichen (") setzen. Sie müssen Ihrem Metadatenlabel weiterhin den String metadata_user_ voranstellen.

Für Diagramme und Dashboards, die vor der UTF-8-Kompatibilität erstellt wurden, werden Cloud Monitoring-Messwerte abgefragt, indem ihre Namen in Legacy-PromQL-kompatible Entsprechungen konvertiert werden. Weitere Informationen zu den alten PromQL-Konvertierungsregeln finden Sie unter Cloud Monitoring-Messwerte altem PromQL zuordnen.

Auf PromQL in Cloud Monitoring zugreifen

Sie können PromQL auf dem Tab Code auf den folgenden Seiten in der Google Cloud -Konsole verwenden:

  • Metrics Explorer
  • Diagramm hinzufügen, wenn Sie benutzerdefinierte Dashboards erstellen

Informationen zum Zugriff auf den Editor und zur Verwendung des Editors finden Sie unter PromQL-Editor verwenden.

PromQL-Regeln und ‑Benachrichtigungen

Sie können mit PromQL Benachrichtigungsrichtlinien für jeden Messwert in Cloud Monitoring erstellen. Weitere Informationen finden Sie unter PromQL-basierte Benachrichtigungsrichtlinien.

Sie können auch PromQL verwenden, um Aufnahme- und Benachrichtigungsregeln für beliebige Messwerte in Cloud Monitoring zu erstellen, indem Sie die In-Cluster-Benachrichtigungen im Prometheus-Stil in Cloud Monitoring verwenden. Weitere Informationen finden Sie unter Verwaltete Regelauswertung und Benachrichtigungen oder Selbst bereitgestellte Regelauswertung und Benachrichtigung.

PromQL lernen

Grundlagen zur Verwendung von PromQL erhalten Sie in der Open-Source-Dokumentation. Die folgenden Ressourcen können Ihnen den Einstieg erleichtern:

Typ der überwachten Ressource angeben

Wenn ein Cloud Monitoring-Messwert nur einem einzelnen von Cloud Monitoring überwachten Ressourcentyp zugeordnet ist, funktioniert die PromQL-Abfrage, ohne manuell einen Ressourcentyp anzugeben. Einige Messwerte innerhalb von Cloud Monitoring, darunter einige Systemmesswerte und viele der von den logbasierten Messwerten generierte Messwerte, lassen sich jedoch mehr als einem Ressourcentyp zuordnen. Wenn Sie einen dieser Messwerte verwenden, insbesondere logbasierte Messwerte, müssen Sie den Ressourcentyp explizit angeben.

Sie können prüfen, welche überwachten Ressourcentypen einem Messwert zugeordnet sind. Gehen Sie dabei so vor:

  • Informationen zu den von Google ausgewählten Messwerten finden Sie in den Listen der verfügbaren Messwerte, einschließlich der Google Cloud-Messwerte und Kubernetes-Messwerte. Jeder Eintrag in der Dokumentation enthält die zugehörigen überwachten Ressourcentypen in der ersten Spalte des jeweiligen Eintrags unter dem Typ. Wenn keine überwachten Ressourcentypen aufgeführt sind, kann der Messwert einem beliebigen Typ zugeordnet werden.

  • Im Metrics Explorer haben Sie folgende Möglichkeiten:

    1. Geben Sie den Namen des Messwerts in das Feld Messwert auswählen ein und wählen Sie ihn dann über die Menüs aus. Im Ressourcenmenü werden gültige Ressourcentypen für diesen Messwert aufgeführt, z. B. „VM-Instanz“.

    2. Klicken Sie in der Symbolleiste des Bereichs „Query Builder“ auf die Schaltfläche mit dem Namen < > PromQL.

      In der angezeigten PromQL-Abfrage wird der Ressourcentyp als Wert des Felds monitored_resource angegeben. Diese Methode ist insbesondere für Messwerte nützlich, die mit vielen überwachten Ressourcentypen verknüpft werden können, z. B. logbasierte Messwerte oder benutzerdefinierte Messwerte.

Wenn ein Messwert mit mehr als einem Ressourcentyp verknüpft ist, müssen Sie den Ressourcentyp in Ihrer PromQL-Abfrage angeben. Mit dem speziellen Label monitored_resource können Sie den Ressourcentyp auswählen.

Überwachte Ressourcentypen sind in den meisten Fällen ein kurzer String wie gce_instance. Gelegentlich werden sie jedoch als vollständige URIs wie monitoring.googleapis.com/MetricIngestionAttribution angezeigt. Korrekt formulierte PromQL-Abfragen können so aussehen:

  • logging_googleapis_com:byte_count{monitored_resource="k8s_container"}
  • custom_googleapis_com:opencensus_opencensus_io_http_server_request_count_by_method{monitored_resource="global"}
  • loadbalancing_googleapis_com:l3_external_egress_bytes_count{monitored_resource="loadbalancing.googleapis.com/ExternalNetworkLoadBalancerRule"}

Der Wert von "" für das Label monitored_resource ist besonders und bezieht sich auf den standardmäßigen prometheus_target-Ressourcentyp, der für Cloud Monitoring-Messwerte verwendet wird.

Wenn Sie das Label monitored_resource nicht verwenden, wenn es benötigt wird, erhalten Sie folgende Fehlermeldung:

metric is configured to be used with more than one monitored resource type; series selector must specify a label matcher on monitored resource name

Labelkonflikte lösen

In Cloud Monitoring können Labels entweder zum Messwert oder zur Ressource gehören. Wenn ein Messwertlabel denselben Schlüsselnamen wie ein Ressourcenlabel hat, können Sie speziell auf das Messwertlabel verweisen, indem Sie dem Labelschlüsselnamen in Ihrer Abfrage das Präfix metric_ hinzufügen.

Angenommen, Sie haben ein Ressourcenlabel und ein Messwertlabel mit dem Namen pod_name im Messwert example.googleapis.com/user/widget_count.

  • Um nach dem Wert des Ressourcenlabels zu filtern, verwenden Sie
    example_googleapis_com:user_widget_count{pod_name="RESOURCE_LABEL_VALUE"}

  • Um nach dem Wert des Messwertlabels zu filtern, verwenden Sie
    example_googleapis_com:user_widget_count{metric_pod_name="METRIC_LABEL_VALUE"}

Cloud Monitoring-Messwertnamen dem alten PromQL zuordnen

Cloud Monitoring-Messwertnamen umfassen zwei Komponenten: eine Domain (z. B. compute.googleapis.com/) und einen Pfad (z. B. instance/disk/max_read_ops_count). Da Legacy-PromQL nur die Sonderzeichen : und _ unterstützt, müssen Sie die folgenden Regeln anwenden, um Monitoring-Messwertnamen mit Legacy-PromQL kompatibel zu machen:

  • Ersetzen Sie den ersten / durch :.
  • Ersetzen Sie alle anderen Sonderzeichen (einschließlich . und anderer /-Zeichen) durch _.

In der folgenden Tabelle sind einige Messwertnamen und ihre Legacy-PromQL-Entsprechungen aufgeführt:

Cloud Monitoring-Messwertname Legacy-PromQL-Messwertname
kubernetes.io/container/cpu/limit_cores kubernetes_io:container_cpu_limit_cores
compute.googleapis.com/instance/cpu/utilization compute_googleapis_com:instance_cpu_utilization
logging.googleapis.com/log_entry_count logging_googleapis_com:log_entry_count
custom.googleapis.com/opencensus/opencensus.io/
http/server/request_count_by_method		 custom_googleapis_com:opencensus_opencensus_io_
http_server_request_count_by_method
agent.googleapis.com/disk/io_time agent_googleapis_com:disk_io_time

Cloud Monitoring-Verteilungsmesswerte können wie Prometheus-Histogramme abgefragt werden, wobei das Suffix _count, _sum oder _bucket an den Messwertnamen angehängt wird:

Cloud Monitoring-Messwertname Legacy-PromQL-Messwertnamen
networking.googleapis.com/vm_flow/rtt networking_googleapis_com:vm_flow_rtt_sum
networking_googleapis_com:vm_flow_rtt_count
networking_googleapis_com:vm_flow_rtt_bucket

PromQL-Kompatibilität

PromQL für Cloud Monitoring funktioniert möglicherweise etwas anders als Upstream-PromQL.

PromQL-Abfragen in Cloud Monitoring werden mithilfe einer internen Abfragesprache teilweise im Monarch-Backend ausgewertet. Es gibt einige bekannte Unterschiede bei den Abfrageergebnissen. Abgesehen von den in diesem Abschnitt aufgeführten Unterschieden entspricht die PromQL in Cloud Monitoring der PromQL, die in Prometheus-Version 2.44 verfügbar ist.

PromQL-Funktionen, die nach Prometheus-Version 2.44 hinzugefügt wurden, werden möglicherweise nicht unterstützt.

UTF-8-Unterstützung

PromQL für Cloud Monitoring unterstützt UTF-8-Abfragen.

Wenn Ihr Prometheus-Messwertname nur aus alphanumerischen Zeichen sowie den Zeichen _ oder : besteht und Ihre Labelschlüssel nur aus alphanumerischen Zeichen sowie dem Zeichen _ bestehen, können Sie die Abfrage mit der herkömmlichen PromQL-Syntax durchführen. Eine gültige Anfrage könnte beispielsweise so aussehen: job:my_metric:sum{label_key="label_value"}.

Wenn in Ihrem Prometheus-Messwertnamen jedoch Sonderzeichen außer _ oder : verwendet werden oder in Ihren Labelschlüsseln Sonderzeichen außer _, müssen Sie Ihre Abfrage gemäß der UTF-8-Spezifikation für PromQL erstellen.

UTF-8-Messwertnamen müssen in Anführungszeichen gesetzt und in die geschweiften Klammern verschoben werden. Labelnamen müssen auch in Anführungszeichen gesetzt werden, wenn sie Zeichen enthalten, die mit der alten Version nicht kompatibel sind. Die folgenden Beispiele für gültige Anfragen sind alle gleichwertig:

  • {"my.domain.com/metric/name_bucket", "label.key"="label.value"}
  • {__name__="my.domain.com/metric/name_bucket", "label.key"="label.value"}
  • {"__name__"="my.domain.com/metric/name_bucket", "label.key"="label.value"}

Abgleich mit Messwertnamen

Es wird nur der exakte Abgleich mit Messwertnamen unterstützt. Ihre Abfrage muss eine genaue Übereinstimmung mit dem Messwertnamen enthalten.

Wir empfehlen die folgenden Problemumgehungen für häufige Szenarien, in denen ein regulärer Ausdrucksabgleich für das Label __name__ verwendet wird:

  • In Prometheus-Adapterkonfigurationen wird häufig der Operator =~ verwendet, um mehrere Messwertnamen abzugleichen. Um dieses Problem zu beheben, erweitern Sie die Konfiguration so, dass für jeden Messwert eine separate Richtlinie verwendet wird, und geben Sie jeden Messwert explizit an. So wird auch verhindert, dass Sie versehentlich Autoscaling für unerwartete Messwerte verwenden.
  • Reguläre Ausdrücke werden häufig verwendet, um mehrere nicht dimensionale Messwerte im selben Diagramm darzustellen. Wenn Sie beispielsweise einen Messwert wie cpu_servicename_usage haben, können Sie einen Platzhalter verwenden, um alle Ihre Dienste zusammen darzustellen. Die Verwendung nicht dimensionaler Messwerte wie dieser ist in Cloud Monitoring ausdrücklich nicht empfehlenswert und führt zu einer extrem schlechten Abfrageleistung. Um dieses Problem zu beheben, müssen Sie alle Dimensionen in Messwertlabels verschieben, anstatt sie in den Messwertnamen einzubetten.
  • Das Abfragen mehrerer Messwerte wird häufig verwendet, um zu sehen, welche Messwerte für Abfragen verfügbar sind. Wir empfehlen stattdessen, die /labels/__name__/values-Funktion zu verwenden, um Messwerte zu ermitteln. Sie können Messwerte auch über die Cloud Monitoring-Benutzeroberfläche ermitteln.
  • Wenn Sie mehrere Messwerte abgleichen, können Sie sehen, wie viele Stichproben pro Messwert erfasst, aufgenommen und abgerechnet wurden. Cloud Monitoring stellt Ihnen diese Informationen auf der Seite Messwertverwaltung zur Verfügung. Sie können auch als Messwertdaten auf diese Informationen zugreifen, indem Sie den Messwert „Erfasste Stichproben“ oder den Messwert „Von Attributions-ID geschriebene Stichproben“ verwenden.

Veraltung

Veralterung wird im Monarch-Backend nicht unterstützt.

Berechnung von irate

Wenn das Lookback-Window für die Funktion irate kleiner als die Schrittgröße ist, wird das Fenster auf die Schrittgröße erhöht. Monarch erfordert diese Änderung, um sicherzustellen, dass keine der Eingabedaten in der Ausgabe vollständig ignoriert werden. Dieser Unterschied gilt auch für rate-Berechnungen.

Berechnung von rate und increase

Wenn das Lookback-Window für die Funktion rate kleiner als die Schrittgröße ist, wird das Fenster auf die Schrittgröße erhöht. Monarch erfordert diese Änderung, um sicherzustellen, dass keine der Eingabedaten in der Ausgabe vollständig ignoriert werden. Dieser Unterschied gilt auch für irate-Berechnungen.

Es gibt Unterschiede bei Interpolations- und Extrapolationsberechnungen. Monarch verwendet einen anderen Interpolationsalgorithmus als Prometheus. Dieser Unterschied kann zu leicht unterschiedlichen Ergebnissen führen. Beispielsweise werden Monarch-Zählerstichproben mit einem Zeitraum gespeichert, nicht mit dem einzelnen Zeitstempel, den Prometheus verwendet. Daher können Zählerstichproben in Monarch in eine Ratenberechnung einbezogen werden, obwohl sie vom Prometheus-Zeitstempel ausgeschlossen werden würden. Das führt in der Regel zu genaueren Raten, insbesondere bei Abfragen am Anfang oder Ende der zugrunde liegenden Zeitachse.

Berechnung von histogram_quantile

Eine PromQL-histogram_quantile-Berechnung in einem Histogramm ohne Stichproben erzeugt einen NaN-Wert. Die Berechnung der internen Abfragesprache erzeugt keinen Wert. Der Punkt am Zeitstempel wird stattdessen ignoriert.

Die Unterschiede bei der Ratenberechnung können sich auch auf die Eingabe für histogram_quantile-Abfragen auswirken.

Typspezifische Funktionen für unterschiedlich typisierte Messwerte

Obwohl das vorgelagerte Prometheus schwach typisiert ist, ist Monarch streng typisiert. Das bedeutet, dass die Ausführung von Funktionen mit spezifischer Typisierung auf einem Messwert mit anderer Typisierung (z. B. rate() auf einem GAUGE-Messwert oder histogram_quantile() auf einem COUNTER- oder nicht typisierten Messwert) in Cloud Monitoring nicht funktioniert, obwohl diese Funktionen im vorgelagerten Prometheus funktionieren.