Abfragen von Prometheus-Metriken mithilfe der API und PromQL

Artikel
10/15/2024

Der verwaltete Azure Monitor-Dienst für Prometheus sammelt Metriken aus Azure Kubernetes-Clustern und speichert sie in einem Azure Monitor-Arbeitsbereich. PromQL (die Prometheus-Abfragesprache) ist eine funktionsbasierte Abfragesprache, mit der Sie Zeitreihendaten abfragen und aggregieren können. Verwenden Sie PromQL zum Abfragen und Aggregieren von Metriken, die in einem Azure Monitor-Arbeitsbereich gespeichert sind.

In diesem Artikel wird beschrieben, wie Sie einen Azure Monitor-Arbeitsbereich mithilfe von PromQL über die REST-API abfragen. Weitere Informationen zu PromQL finden Sie unter Abfragen von Prometheus.

Voraussetzungen

Zum Abfragen eines Azure Monitor-Arbeitsbereichs mit PromQL müssen folgende Voraussetzungen erfüllt sein:

Ein Azure Kubernetes-Cluster oder ein Kubernetes-Remotecluster
Verwalteter Azure Monitor-Dienst für Prometheus für das Auslesen von Metriken aus einem Kubernetes-Cluster.
Ein Azure Monitor-Arbeitsbereich, in dem Prometheus-Metriken gespeichert werden

Authentifizierung

Zum Abfragen des Azure Monitor-Arbeitsbereichs authentifizieren Sie sich mit Microsoft Entra ID. Die API unterstützt die Microsoft Entra-Authentifizierung mit Clientanmeldeinformationen. Registrieren Sie eine Client-App bei Microsoft Entra ID, und fordern Sie ein Token an.

Führen Sie zum Einrichten der Microsoft Entra-Authentifizierung die folgenden Schritte aus:

Sie registrieren eine App mit Microsoft Entra ID.
Gewähren Sie der App Zugriff auf Ihren Azure Monitor-Arbeitsbereich.
Fordern Sie ein Token an.

Sie registrieren eine App mit Microsoft Entra ID

Führen Sie zum Registrieren einer App die Schritte unter Registrieren einer App zum Anfordern von Autorisierungstoken und Arbeiten mit APIs aus.

Gewähren des App-Zugriffs auf Ihren Arbeitsbereich

Weisen Sie Ihrer App die Rolle Überwachungsdatenleser hinzu, damit sie Ihre Daten aus Ihrem Azure Monitor-Arbeitsbereich abfragen kann.

Öffnen Sie den Azure Monitor-Arbeitsbereich im Azure-Portal.
Notieren Sie auf der Übersichtsseite Ihren Abfrageendpunkt zur Verwendung in Ihrer REST-Anforderung.
Wählen Sie die Option „Zugriffssteuerung (IAM)“ aus.
Wählen Sie Hinzufügen und dann auf der Seite Zugriffssteuerung (IAM) die Option Rollenzuweisung hinzufügen aus.
Suchen Sie auf der Seite Rollenzuweisung hinzufügen nach Überwachung.
Wählen Sie Überwachungsdatenleser und dann die Registerkarte „Mitglieder“ aus.
Wählen Sie Mitglieder auswählen aus.
Suchen Sie nach der App, die Sie registriert haben, und wählen Sie sie aus.
Klicken Sie auf Auswählen.
Wählen Sie Überprüfen und zuweisen aus.

Sie haben Ihre App-Registrierung erstellt und ihr Zugriff zum Abfragen von Daten aus Ihrem Azure Monitor-Arbeitsbereich erteilt. Sie können jetzt ein Token generieren und es in einer Abfrage verwenden.

Anfordern eines Tokens

Senden Sie die folgende Anforderung über die Eingabeaufforderung oder mithilfe eines Clients wie Insomnia oder der Invoke-RestMethod von PowerShell.

curl -X POST 'https://login.microsoftonline.com/<tenant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret>' \
--data-urlencode 'resource=https://prometheus.monitor.azure.com'

Beispiel für Antworttext:

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https:/prometheus.monitor.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

Speichern Sie das Zugriffstoken aus der Antwort, um es in den folgenden HTTP-Anforderungen zu verwenden.

Abfrageendpunkt

Suchen Sie den Abfrageendpunkt Ihres Azure Monitor-Arbeitsbereichs auf der Übersichtsseite des Azure Monitor-Arbeitsbereichs.

Unterstützte APIs

Die folgenden Abfragen werden unterstützt:

Sofortige Abfragen

Weitere Informationen finden Sie unter Sofortige Abfragen.

Pfad: /api/v1/query
Beispiele:

POST https://k8s-02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query  
--header 'Authorization:  Bearer <access token>'
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'query=sum( \
    container_memory_working_set_bytes \
    * on(namespace,pod) \
    group_left(workload, workload_type) \
    namespace_workload_pod:kube_pod_owner:relabel{ workload_type="deployment"}) by (pod)'

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query?query=container_memory_working_set_bytes' 
--header 'Authorization:  Bearer <access token>'

Bereichsabfragen

Weitere Informationen finden Sie unter Bereichsabfragen.
Pfad: /api/v1/query_range
Beispiele:

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query_range?query=container_memory_working_set_bytes&start=2023-03-01T00:00:00.000Z&end=2023-03-20T00:00:00.000Z&step=6h'
--header 'Authorization: Bearer <access token>

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query_range' 
--header 'Authorization:  Bearer <access token>'
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'query=up' 
--data-urlencode 'start=2023-03-01T20:10:30.781Z' 
--data-urlencode 'end=2023-03-20T20:10:30.781Z' 
--data-urlencode 'step=6h'

Reihen

Weitere Informationen finden Sie unter Reihen.

Pfad: /api/v1/series
Beispiele:

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/series' 
--header 'Authorization: Bearer <access token>
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'match[]=kube_pod_info{pod="bestapp-123abc456d-4nmfm"}'

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/series?match[]=container_network_receive_bytes_total{namespace="default-1669648428598"}'

Bezeichnungen

Weitere Informationen finden Sie unter Bezeichnungen. Pfad: /api/v1/labels
Beispiele:

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/labels'

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/labels'

Bezeichnungswerte

Weitere Informationen finden Sie unter Bezeichnungswerte.
Pfad: /api/v1/label/__name__/values.

Hinweis

__name__ ist die einzige unterstützte Version dieser API und gibt alle Metriknamen zurück. Andere „/api/v1/label/<label_name>/values“-Pfade werden nicht unterstützt.

Beispiel:

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/label/__name__/values'

Die vollständige Spezifikation der OSS-Prom-APIs finden Sie unter Prometheus-HTTP-API.

API-Einschränkungen

Die folgenden Einschränkungen gelten zusätzlich zu den Einschränkungen, die in der Prometheus-Spezifikation beschrieben sind.

Geltungsbereich einer Abfrage muss auf eine Metrik festgelegt werden
Alle Abfragen für den Abruf von Zeitreihen („/series“ oder „/query“ oder „/query_range“) müssen einen „__name__“-Bezeichnungsabgleich enthalten. Das heißt, jede Abfrage muss auf eine Metrik festgelegt werden. In einer Abfrage kann nur ein „__name__“-Bezeichnungsabgleich vorhanden sein.
Die Abfrage /series unterstützt keinen Filter für reguläre Ausdrücke
Unterstützter Zeitbereich
- Die „/query_range“-API unterstützt einen Zeitbereich von 32 Tagen. Dies ist der maximal zulässige Zeitbereich, einschließlich der Bereichsselektoren, die in der Abfrage selbst angegeben sind. Die Abfrage rate(http_requests_total[1h] für die letzten 24 Stunden würde beispielsweise bedeuten, dass Daten für 25 Stunden abgefragt werden. Dies ergibt sich aus der Zeitspanne von 24 Stunden plus der in der Abfrage selbst angegebenen 1 Stunde.
- Die „/series“-API ruft Daten für einen maximalen Zeitraum von 12 Stunden ab. Wenn endTime nicht angegeben wird, gilt „endTime = time.now()“. Wenn der Zeitbereich mehr als 12 Stunden umfasst, wird startTime auf endTime – 12h festgelegt.
Ignorierter Zeitbereich
Start- und Endzeit, die mit /labels und /label/__name__/values bereitgestellt werden, werden ignoriert, und alle gespeicherten Daten im Azure Monitor-Arbeitsbereich werden abgefragt.
Experimentelle Features
Experimentelle Features wie Exemplare werden nicht unterstützt.

Weitere Informationen zu Grenzwerten für Prometheus-Metriken finden Sie unter Prometheus-Metriken.

Groß- und Kleinschreibung

Von Azure verwaltetes Prometheus ist ein System, bei dem die Groß-/Kleinschreibung nicht beachtet wird. Es behandelt Zeichenfolgen (z. B. Metriknamen, Bezeichnungsnamen oder Bezeichnungswerte) als die gleiche Zeitreihe, wenn sie sich von einer anderen Zeitreihe nur durch die Groß-/Kleinschreibung unterscheiden.

Hinweis

Dieses Verhalten unterscheidet sich vom nativem Open Source-Prometheus, bei dem die Groß-/Kleinschreibung beachtet wird.
Selbstverwaltete Prometheus-Instanzen, die auf Azure-VMs, in VMSSs oder Azure Kubernetes Service-Clustern (AKS) ausgeführt werden, sind Systeme mit Beachtung der Groß-/Kleinschreibung.

In von Azure verwaltetem Prometheus werden die folgenden Zeitreihen als identisch angesehen:

diskSize(cluster="eastus", node="node1", filesystem="usr_mnt")
diskSize(cluster="eastus", node="node1", filesystem="usr_MNT")

Die obigen Beispiele sind eine einzelne Zeitreihe in einer Zeitreihendatenbank.

Alle Stichproben, die für sie erfasst wurden, werden so gespeichert, als ob sie mit einer einzigen Zeitreihe ausgelesen/erfasst würden.
Wenn die obigen Beispiele mit dem gleichen Zeitstempel erfasst werden, wird eines von ihnen nach dem Zufallsprinzip verworfen.
Die Groß-/Kleinschreibung, die in der Zeitreihendatenbank gespeichert und von einer Abfrage zurückgegeben wird, ist unvorhersehbar. Unterschiedliche Groß-/Kleinschreibungen können zu unterschiedlichen Zeiten für die gleiche Zeitreihe zurückgegeben werden.
Jeder in der Abfrage vorhandene Metrikname oder Bezeichnungsnamen/Bezeichniswert-Matcher wird aus der Zeitreihendatenbank abgerufen, indem ein Vergleich ohne Berücksichtigung der Groß-/Kleinschreibung durchgeführt wird. Wenn in einer Abfrage ein Matcher mit Berücksichtigung der Groß-/Kleinschreibung vorhanden ist, wird er beim Durchführen von Zeichenfolgenvergleichen automatisch als Matcher ohne Berücksichtigung der Groß-/Kleinschreibung behandelt.

Es empfiehlt sich, sicherzustellen, dass eine Zeitreihe mit einem einer einzelnen Groß-/Kleinschreibung erstellt oder ausgelesen wird.

In der Open Source-Lösung für Prometheus werden die obigen Zeitreihen als zwei verschiedene Zeitreihen behandelt. Alle Stichproben, die mit ihnen ausgelesen/erfasst werden, werden separat gespeichert.

Häufig gestellte Fragen

Dieser Abschnitt enthält Antworten auf häufig gestellte Fragen.

Mir fehlen alle oder einige meiner Metriken. Wie behebe ich dieses Problem?

Sie können hier den Leitfaden zur Problembehandlung zum Erfassen von Prometheus-Metriken vom verwalteten Agent verwenden.

Warum fehlen Metriken mit zwei Bezeichnungen mit demselben Namen, aber unterschiedlicher Groß-/Kleinschreibung?

Von Azure verwaltetes Prometheus ist ein System, bei dem die Groß-/Kleinschreibung nicht beachtet wird. Es behandelt Zeichenfolgen (z. B. Metriknamen, Bezeichnungsnamen oder Bezeichnungswerte) als die gleiche Zeitreihe, wenn sie sich nur durch die Groß-/Kleinschreibung der Zeichenfolge von einer anderen Zeitreihe unterscheiden. Weitere Informationen finden Sie unter Übersicht über Prometheus-Metriken.

Warum sehe ich einige Lücken in Metrikdaten?

Bei Knotenaktualisierungen kann eine Lücke von 1 bis 2 Minuten in den Metrikdaten für Metriken auftreten, die von unseren Collectors auf Clusterebene erfasst wurden. Diese Lücke tritt auf, da der Knoten, auf dem die Daten ausgeführt werden, im Rahmen eines normalen Aktualisierungsprozesses aktualisiert wird. Dieser Aktualisierungsprozess wirkt sich auf clusterweite Ziele aus, z. B. kube-state-metrics und benutzerdefinierte Anwendungsziele, die angegeben werden. Dies tritt auf, wenn Ihr Cluster manuell oder per automatischer Aktualisierung aktualisiert wird. Dies ist das erwartete Verhalten, und es tritt aufgrund der Aktualisierung des Knotens auf, auf dem er ausgeführt wird. Dieses Verhalten wirkt sich nicht auf unsere empfohlenen Warnungsregeln aus.

Nächste Schritte

Übersicht über den Azure Monitor-Arbeitsbereich
Verwalten eines Azure Monitor-Arbeitsbereichs
Übersicht über den verwalteten Azure Monitor-Dienst für Prometheus
Abfragen von Prometheus-Metriken mithilfe von Azure-Arbeitsmappen

Freigeben über