Nachdem Sie Messwerte von Ihren bereitgestellten Arbeitslasten in Google Distributed Cloud (GDC) mit Air Gap erfasst haben, können Sie mit der Analyse beginnen. Zum Analysieren von Messwerten können Sie sie auf informativen Grafana-Dashboards visualisieren und filtern oder mit dem curl-Tool für flexibles Scripting und Automatisierung direkt über Cortex darauf zugreifen.
Auf dieser Seite finden Sie detaillierte Anleitungen zum Abfragen und Visualisieren Ihrer Messwerte mit der Grafana-Benutzeroberfläche und dem curl-Tool für den Cortex-Endpunkt, um Einblicke in die Leistung Ihrer Arbeitslast zu erhalten.
Sie können auf zwei Arten auf Ihre Messwerte zugreifen:
- Grafana-Dashboards: Trends untersuchen und Anomalien mit intuitiven Visualisierungen wichtiger Messwerte wie CPU-Auslastung, Speicherverbrauch und Netzwerkaktivität erkennen. Grafana bietet eine nutzerfreundliche Oberfläche zum Filtern und Analysieren Ihrer Arbeitslastdaten in Dashboards.
- Cortex-Endpunkt: Für komplexere Anwendungsfälle können Sie die Cortex-Instanz Ihres Projekts direkt über die Befehlszeile mit dem Tool
curlabfragen. Cortex speichert die Prometheus-Messwerte Ihres Projekts und stellt einen HTTP-Endpunkt für den programmatischen Zugriff bereit. Mit diesem Zugriff können Sie Daten exportieren, Aufgaben automatisieren und benutzerdefinierte Integrationen erstellen.
Hinweis
Bitten Sie Ihren IAM-Organisationsadministrator oder IAM-Projektadministrator, Ihnen eine der vordefinierten Rollen „Organization Grafana Viewer“ oder „Project Grafana Viewer“ zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Abfragen und Visualisieren von Messwerten in Grafana-Dashboards benötigen. Je nach erforderlicher Zugriffsebene und Berechtigungen können Sie Grafana-Rollen in einer Organisation oder einem Projekt erhalten.
Alternativ können Sie Ihren IAM-Projektadministrator bitten, Ihnen die Rolle „Project Cortex Prometheus Viewer“ in Ihrem Projekt-Namespace zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Abfragen von Messwerten vom Cortex-Endpunkt benötigen.
In der folgenden Tabelle sind die Role-Anforderungen für die Personas „PA“ und „AO“ zusammengefasst.
| Persona | Objekt | Cluster | Rolle | Namespace | Gruppe/Nutzer | Konfiguration |
|---|---|---|---|---|---|---|
| PA | grafana | org-admin | project-grafana-viewer |
platform-obs | Gruppe | 1 |
| PA | Cortex | org-admin | project-cortex-prometheus-viewer |
platform-obs | Gruppe | 2 |
| PA | grafana | org-admin | project-grafana-viewer |
platform-obs | Nutzer | 3 |
| PA | Cortex | org-admin | project-cortex-prometheus-viewer |
platform-obs | Nutzer | 4 |
| AO | grafana | org-admin | project-grafana-viewer |
PROJECT_NAMESPACE | Gruppe | 1 |
| AO | Cortex | org-admin | project-cortex-prometheus-viewer |
PROJECT_NAMESPACE | Gruppe | 2 |
| AO | grafana | org-admin | project-grafana-viewer |
PROJECT_NAMESPACE | Nutzer | 3 |
| AO | Cortex | org-admin | project-cortex-prometheus-viewer |
PROJECT_NAMESPACE | Nutzer | 4 |
Ersetzen Sie die folgenden Variablen entsprechend:
| Variable | Beschreibung |
|---|---|
KUBECONFIG |
Sie benötigen die kubeconfig-Datei für den spezifischen Cluster, der die NAMESPACE enthält, auf die diese RoleBinding angewendet wird. |
RULE_NAME |
Der eindeutige Name für diese RoleBinding-Ressource innerhalb des Namespace. Beispiel: io-root-cortex-prometheus-viewer. |
NAMESPACE |
Der Kubernetes-Namespace, in dem diese RoleBinding erstellt und angewendet wird. Suchen Sie in der vorherigen Tabelle nach der Spalte Namespace. |
EMAIL_ADDRESS |
Die Kennung für den Nutzer, dem die Rolle zugewiesen wird. Dies ist häufig eine E‑Mail-Adresse. Beispiel: infrastructure-operator@example.com. |
ROLE |
Der Name der Role, die die Berechtigungen enthält, die Sie dem Nutzer gewähren möchten. Suchen Sie nach den Rollen, die in der vorherigen Tabelle verfügbar sind. |
GROUP_NAME |
Der Name des Group, zu dem der PA/AO-Nutzer gehört. Beispiel: pa-group. |
ZONE |
Name der Zone |
Konfiguration 1
Mit dieser Konfiguration werden einer Nutzergruppe Berechtigungen für den Zugriff auf PA/AO Grafana im Cluster org gewährt. Nachdem Sie diese Konfiguration eingerichtet haben, finden Sie im Abschnitt Grafana-Dashboards dieses Dokuments Informationen zum Aufrufen von Messwerten in Grafana.
Kubectl-Befehl
Dies ist das allgemeine Befehlsformat:
kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --group=`GROUP_NAME` --role=project-grafana-viewerBeispiel:
kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --group=my-team --namespace=platform-obsIAC-Dateipfad
/infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`GROUP_NAME`/<YAML_FILE>YAML-Datei
apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: RULE_NAME namespace: platform-obs subjects: - kind: Group name: GROUP_NAME apiGroup: rbac.authorization.k8s.io roleRef: kind: Role name: project-grafana-viewer apiGroup: rbac.authorization.k8s.io
Konfiguration 2
Mit dieser Konfiguration werden einer Nutzergruppe Berechtigungen gewährt, um programmatisch auf PA/AO-Messwerte im Cluster org zuzugreifen. Nachdem Sie diese Konfiguration eingerichtet haben, lesen Sie den Abschnitt Cortex-Endpunkt in diesem Dokument, um die Messwerte programmatisch abzufragen.
Kubectl-Befehl
Dies ist das allgemeine Befehlsformat:
kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --group=`GROUP_NAME` --role=project-cortex-prometheus-viewerBeispiel:
kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-cortex-prometheus-viewer-binding --role=project-cortex-prometheus-viewer --group=my-team --namespace=platform-obsIAC-Dateipfad
/infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`GROUP_NAME`/<YAML_FILE>YAML-Datei
apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: RULE_NAME namespace: platform-obs subjects: - kind: Group name: GROUP_NAME apiGroup: rbac.authorization.k8s.io roleRef: kind: Role name: project-cortex-prometheus-viewer apiGroup: rbac.authorization.k8s.io
Konfiguration 3
Mit dieser Konfiguration werden einem Nutzer Berechtigungen für den Zugriff auf PA/AO Grafana im Cluster org gewährt. Nachdem Sie diese Konfiguration eingerichtet haben, finden Sie im Abschnitt Grafana-Dashboards dieses Dokuments Informationen zum Aufrufen von Messwerten in Grafana.
Kubectl-Befehl
Dies ist das allgemeine Befehlsformat:
kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --user=`EMAIL_ADDRESS` --role=project-grafana-viewerBeispiel:
kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --user=my-email@example.com --namespace=platform-obsIAC-Dateipfad
/infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`EMAIL_ADDRESS`/<YAML_FILE>YAML-Datei
apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: RULE_NAME namespace: platform-obs subjects: - kind: User name: EMAIL_ADDRESS apiGroup: rbac.authorization.k8s.io roleRef: kind: Role name: project-grafana-viewer apiGroup: rbac.authorization.k8s.io
Konfiguration 4
Mit dieser Konfiguration werden einem Nutzer Berechtigungen gewährt, um programmatisch auf PA/AO-Messwerte im Cluster org zuzugreifen. Nachdem Sie diese Konfiguration eingerichtet haben, lesen Sie den Abschnitt Cortex-Endpunkt in diesem Dokument, um die Messwerte programmatisch abzufragen.
Kubectl-Befehl
Dies ist das allgemeine Befehlsformat:
kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --user=`EMAIL_ADDRESS` --role=project-cortex-prometheus-viewerBeispiel:
kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-cortex-prometheus-viewer-binding --role=project-cortex-prometheus-viewer --user=my-email@example.com --namespace=platform-obsIAC-Dateipfad
/infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`EMAIL_ADDRESS`/<YAML_FILE>YAML-Datei
apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: RULE_NAME namespace: platform-obs subjects: - kind: User name: EMAIL_ADDRESS apiGroup: rbac.authorization.k8s.io roleRef: kind: Role name: project-cortex-prometheus-viewer apiGroup: rbac.authorization.k8s.io
Weitere Informationen zu diesen Rollen finden Sie unter IAM-Berechtigungen vorbereiten.
Messwerte abrufen und filtern
Wählen Sie eine der folgenden Methoden aus, um Abfragen zu erstellen, Trends zu visualisieren und Messwerte aus Ihren Projektarbeitslasten zu filtern:
Grafana-Dashboards
In diesem Abschnitt wird beschrieben, wie Sie über Grafana-Dashboards auf Ihre Messwerte zugreifen.
Grafana-Endpunkt identifizieren
Die folgende URL ist der Endpunkt der Grafana-Instanz Ihres Projekts:
https://GDC_URL/PROJECT_NAMESPACE/grafana
Ersetzen Sie Folgendes:
GDC_URL: die URL Ihrer Organisation in GDC.PROJECT_NAMESPACE: Ihr Projekt-Namespace.Der Grafana-Endpunkt für das Projekt
platform-obsin der Organisationorg-1lautet beispielsweisehttps://org-1/platform-obs/grafana.
Messwerte in der Grafana-Benutzeroberfläche ansehen
Rufen Sie Messwerte in der Grafana-Benutzeroberfläche ab:
- Wählen Sie in der GDC-Konsole Ihr Projekt aus.
- Wählen Sie im Navigationsmenü Vorgänge > Monitoring aus.
Klicken Sie auf Alle in Grafana ansehen.
Auf einer neuen Seite wird der Grafana-Endpunkt geöffnet und die Benutzeroberfläche angezeigt.
Klicken Sie auf der Benutzeroberfläche im Navigationsmenü auf Expl. Datenanalyse Expl. Datenanalyse, um die Seite Expl. Datenanalyse zu öffnen.
Wählen Sie im Menü in der Leiste Explore eine Datenquelle aus, um Messwerte entsprechend Ihrem Universumstyp abzurufen:
Universen mit einer einzelnen Zone: Wählen Sie prometheus aus, um Messwerte aus der einzelnen Zone Ihres Universums anzuzeigen.
Universen mit mehreren Zonen: Grafana kann eine Verbindung zu verschiedenen Zonen herstellen und zonenübergreifende Daten anzeigen. Wählen Sie Messwerte ZONE_NAME aus, um Messwerte aus einer beliebigen Zone Ihres Universums anzuzeigen, unabhängig davon, in welcher Zone Sie angemeldet sind.
Wenn Sie außerdem zonenübergreifende Datenvisualisierungen in einem einzigen Dashboard haben und Ihrer Abfrage mehrere Zonen hinzufügen möchten, wählen Sie Gemischt als Datenquelle aus.
Geben Sie eine Abfrage ein, um mit PromQL-Ausdrücken (Prometheus Query Language) nach Messwerten zu suchen. Sie können diesen Schritt über eine der beiden folgenden Methoden ausführen:
- Wählen Sie in den Menüs Messwert und Labelfilter einen Messwert und ein Label für Ihre Abfrage aus. Klicken Sie auf Hinzufügen Hinzufügen, um Ihrer Abfrage weitere Labels hinzuzufügen. Klicken Sie dann auf Abfrage ausführen.
- Geben Sie Ihre Abfrage direkt in das Textfeld Messwerte ein und drücken Sie Umschalttaste + Eingabetaste, um die Abfrage auszuführen.
Auf der Seite werden die Messwerte angezeigt, die Ihrer Abfrage entsprechen.
Abbildung 1. Menüoption zum Abfragen von Messwerten über die Grafana-Benutzeroberfläche.
In Abbildung 1 wird mit der Option prometheus die Oberfläche angezeigt, über die Sie Abfragen aus Grafana erstellen können, um Messwerte abzurufen.
Beispiele für Werte von Labels, die Sie zum Abfragen von Messwerten verwenden können, finden Sie unter Beispielabfragen und ‑labels.
Cortex-Endpunkt – einzelne Zone
In diesem Abschnitt wird beschrieben, wie Sie mit Cortex auf Ihre Messwerte zugreifen.
Cortex-Endpunkt identifizieren
Die folgende URL ist der Endpunkt der Cortex-Instanz Ihres Projekts:
https://GDC_URL/PROJECT_NAMESPACE/cortex/prometheus/
Ersetzen Sie Folgendes:
GDC_URL: die URL Ihrer Organisation in GDC.PROJECT_NAMESPACE: Ihr Projekt-Namespace.Der Cortex-Endpunkt für das Projekt
platform-obsin der Organisationorg-1lautet beispielsweisehttps://org-1/platform-obs/cortex/prometheus/.
curl-Anfrage authentifizieren
- Laden Sie die gdcloud CLI herunter und installieren Sie sie.
Legen Sie das gdcloud-Attribut
core/organization_console_urlfest:gdcloud config set core/organization_console_url https://GDC_URLMelden Sie sich mit dem konfigurierten Identitätsanbieter an:
gdcloud auth loginVerwenden Sie Ihren Nutzernamen und Ihr Passwort, um sich zu authentifizieren und anzumelden.
Wenn die Anmeldung erfolgreich ist, können Sie den Autorisierungsheader in Ihrer curl-Anfrage über den Befehl
gdcloud auth print-identity-tokenverwenden. Weitere Informationen finden Sie unter gdcloud auth.
Cortex-Endpunkt aufrufen
Führen Sie die folgenden Schritte aus, um den Cortex-Endpunkt mit dem curl-Tool zu erreichen:
curl-Anfrage authentifizierenVerwenden Sie
curl, um den Cortex-Endpunkt aufzurufen, und erweitern Sie die URL mit dem HTTP API-Format für Abfragen, um Messwerte abzufragen.Das folgende Beispiel zeigt eine
curl-Anfrage:curl https://GDC_URL/PROJECT_NAME/cortex/prometheus/api/v1/query?query=my_metric{cluster="my-cluster"}&time=2015-07-01T20:10:51.781Z \ -H "Authorization: Bearer $(gdcloud auth print-identity-token \ --audiences=https://GDC_URL)"Sie erhalten die Ausgabe nach dem Befehl. Die API-Antwort ist im JSON-Format.
Cortex-Endpunkt – Multizone
In diesem Abschnitt wird beschrieben, wie Sie mit Cortex auf Ihre Messwerte zugreifen.
Cortex-Endpunkt identifizieren
Die folgende URL ist der Endpunkt der Cortex-Instanz Ihres Projekts für die multizonale Abfrage:
https://GDC_URL/PROJECT_NAMESPACE/cortex/metrics
Ersetzen Sie Folgendes:
GDC_URL: die URL Ihrer Organisation in GDC.- Beispiel für org-1, zone1:
console.org-1.zone1.google.gdch.test - Ersetzen Sie die Organisation und die Zone für Ihre Anwendung.
- Beispiel für org-1, zone1:
PROJECT_NAMESPACE: Ihr Projekt-Namespace.Der Cortex-Endpunkt für das Projekt
project-1in der Organisationorg-1lautet beispielsweisehttps://console.org-1.zone1.google.gdch.test/project-1/cortex/metrics..
curl-Anfrage authentifizieren
- Laden Sie die gdcloud CLI herunter und installieren Sie sie.
Legen Sie das gdcloud-Attribut
core/organization_console_urlfest:gdcloud config set core/organization_console_url https://GDC_URLMelden Sie sich mit dem konfigurierten Identitätsanbieter an:
gdcloud auth loginVerwenden Sie Ihren Nutzernamen und Ihr Passwort, um sich zu authentifizieren und anzumelden.
Wenn die Anmeldung erfolgreich ist, können Sie den Autorisierungsheader in Ihrer curl-Anfrage über den Befehl
gdcloud auth print-identity-tokenverwenden. Weitere Informationen finden Sie unter gdcloud auth.
Cortex-Endpunkt aufrufen
Führen Sie die folgenden Schritte aus, um den Cortex-Endpunkt mit dem curl-Tool zu erreichen:
curl-Anfrage authentifizieren- Verwenden Sie
curl, um den Cortex-Endpunkt aufzurufen, und erweitern Sie die URL mit dem HTTP API-Format für Abfragen, um Messwerte abzufragen. Geben Sie zusätzlich zu den Prometheus-URL-Abfrageparametern den Standortparameter an, um eine Liste der Zonen bereitzustellen, die abgefragt werden sollen. - location={string}: Liste der Zonen, getrennt durch
|- Wenn nicht angegeben, wird die Abfrage für alle verfügbaren Zonen ausgeführt.Das folgende Beispiel zeigt eine
curl POST-Anfrage:curl POST \ https://GDC_URL/PROJECT_NAME/cortex/metrics/api/v1/query_range" \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'query=pod_cpu_usage_total' \ --data-urlencode 'start=2025-07-21T16:00:00Z' \ --data-urlencode 'end=2025-07-21T16:15:00Z' \ --data-urlencode 'step=60s' \ --data-urlencode 'location=zone1|zone2' \ -H "Authorization: Bearer $(gdcloud auth print-identity-token \ --audiences=https://GDC_URL)"Das folgende Beispiel zeigt eine
curl GET-Anfrage:curl -X GET \ https://GDC_URL/PROJECT_NAME/cortex/metrics/api/v1/query_range?query=pod_cpu_usage_total&start=2025-07-21T16:00:00Z&end=2025-07-21T16:15:00Z&step=1s&location=zone1|zone2" \ -H "Authorization: Bearer $(gdcloud auth print-identity-token \ --audiences=https://GDC_URL)"Sie erhalten die Ausgabe nach dem Befehl. Die API-Antwort ist im JSON-Format.
Beispielabfragen und ‑labels
Sie können Messwerte mithilfe des Messwertnamens und der Schlüssel/Wert-Paare für Labels abfragen. Eine PromQL-Abfrage hat die folgende Syntax:
metric_name{label_one="value", label_two="value"}
Mit Labels können Sie die Merkmale eines Messwerts unterscheiden. Auf diese Weise können Containerautoren ihre Arbeitslasten so konfigurieren, dass Messwerte generiert und Tags hinzugefügt werden, um diese Messwerte zu filtern.
Sie können beispielsweise den Messwert api_http_requests_total verwenden, um die Anzahl der empfangenen HTTP-Anfragen zu zählen. Anschließend können Sie diesem Messwert ein request_method-Label hinzufügen, das den Wert POST, GET oder PUT annimmt. Daher erstellen Sie drei Messwertstreams für jeden Anfragetyp, den Sie möglicherweise erhalten. In diesem Fall führen Sie die folgende Abfrage aus, um die Anzahl der HTTP-GET-Anfragen zu ermitteln:
api_http_requests_total{request_method="GET"}
Weitere Informationen zu Messwerten und Labels finden Sie unter Messwerte und Labelnamen.
Im Folgenden sind einige der Standardlabels aufgeführt, die von der benutzerdefinierten Ressource MonitoringTarget hinzugefügt werden. Sie können diese Standardlabels verwenden, um Messwerte abzufragen:
_gdch_service: der Kurzname des Dienstes.clusterist der Name des Clusters.container_name: der Name des Containers in einem Pod.namespace_name: Ihr Projekt-Namespace.pod_name: das Präfix des Pod-Namens.
In der folgenden Tabelle werden die Labels beschrieben, die Prometheus automatisch hinzufügt:
| Messwertlabel | Beschreibung |
|---|---|
job |
Der interne Name des Scraping-Jobs, der zum Erfassen des Messwerts verwendet wird. Jobs, die von der benutzerdefinierten Ressource MonitoringTarget erstellt werden, haben einen Namen mit dem folgenden Muster:obs-system/OBS_SHADOW_PROJECT_NAME/MONITORINGTARGET_NAME.MONITORINGTARGET_NAMESPACE/I/JI und J sind eindeutige Nummern, die intern festgelegt werden, um Namenskonflikte zu vermeiden. |
instance |
Der $IP:$PORT des gelöschten Dienstes. Wenn eine Arbeitslastressource mehrere Replikate hat, können Sie sie mit diesem Feld unterscheiden. |
Das folgende Codebeispiel zeigt die Verwendung von Schlüssel/Wert-Paaren für Labels, um verschiedene Messwerte abzufragen und die in einem Kubernetes-Cluster erfasste CPU-Auslastung aufzurufen:
pod_cpu_usage_total{cluster="CLUSTER_NAME"}
Mit dem Tool zum Umbenennen von Messwerten können Sie Labels hinzufügen, die von den extrahierten Containern nicht ursprünglich bereitgestellt wurden, und erstellte Messwerte umbenennen. Sie müssen die benutzerdefinierte Ressource MonitoringTarget konfigurieren, um den erfassten Messwerten Labels hinzuzufügen.
Geben Sie diese Labels im Feld metricsRelabelings der benutzerdefinierten Ressource an.
Weitere Informationen finden Sie unter Labelmesswerte.
Hier ist ein Beispiel für eine Antwort, die von einem Cortex-Messwertendpunkt empfangen wurde:
{
"zone1": {
"status": "success",
"data": {
"resultType": "matrix",
"result": [
{
"metric": {
"__name__": "pod_cpu_usage_total",
"_gdch_project": "project-1",
"cluster": "root-admin",
"container_name": "otel-collector",
"exported_instance": "localhost:2112",
"exported_job": "workload-0",
"ha_cluster": "root-admin-shard1",
"instance": "172.192.1.74:3113",
"job": "metrics-server-exporter.mon-system",
"namespace": "mon-system",
"namespace_name": "mon-system",
"pod": "cortex-0",
"pod_name": "metrics-server-exporter-695c9f848b-swzgq",
"zone_id": "zone1"
},
"values": [
[
1753261200,
"2.258621991"
],
[
1753261800,
"1.029301454"
]
]
}
]
}
},
"zone2": {
"status": "success",
"data": {
"resultType": "matrix",
"result": [
{
"metric": {
"__name__": "pod_cpu_usage_total",
"_gdch_project": "project-1",
"cluster": "root-admin",
"container_name": "otel-collector",
"exported_instance": "localhost:2112",
"exported_job": "workload-0",
"ha_cluster": "root-admin-shard1",
"instance": "172.196.3.208:3113",
"job": "metrics-server-exporter.mon-system",
"namespace": "mon-system",
"namespace_name": "mon-system",
"pod": "cortex-0",
"pod_name": "metrics-server-exporter-695c9f848b-kchfv",
"zone_id": "zone2"
},
"values": [
[
1753261200,
"1.814027424"
],
[
1753261800,
"2.7767060260000003"
]
]
}
]
}
}
}
HTTP API abfragen
Formatübersicht
Die API-Antworten sind einheitlich im JSON-Format formatiert. Erfolgreiche Anfragen erhalten immer einen 2xx-Statuscode.
Bei ungültigen Anfragen geben die API-Handler ein JSON-Fehlerobjekt zusammen mit einem der folgenden HTTP-Statuscodes zurück:
- 400 Ungültige Anfrage: Wenn wichtige Parameter fehlen oder falsch angegeben sind.
- 503 Service Unavailable: Wenn Abfragen das Zeitlimit überschreiten oder abgebrochen werden.
Alle erfolgreich erhobenen Daten werden im Feld „data“ der Antwort aufgeführt.
Das JSON-Antwort-Envelope-Format sieht so aus:
{
"status": "success" | "error",
"data": <data>,
// Only set if status is "error". The data field may still hold
// additional data.
"errorType": "<string>",
"error": "<string>",
// Only set if there were warnings while executing the request.
// There will still be data in the data field.
"warnings": ["<string>"],
// Only set if there were info-level annotations while executing the request.
"infos": ["<string>"]
}
Instant-Abfragen
Der folgende Endpunkt wertet eine Sofortabfrage zu einem einzelnen Zeitpunkt aus:
GET /api/v1/query
POST /api/v1/query
Die folgenden URL-Abfrageparameter sind für Prometheus-Ausdrucksabfragen verfügbar:
query=<string>: Der Prometheus-Ausdrucksabfragestring.time=<rfc3339 | unix_timestamp>: Ein optionaler Bewertungszeitstempel, angegeben als RFC 3339-String oder Unix-Zeitstempel. Wenn nichts angegeben ist, wird die aktuelle Serverzeit verwendet.timeout=<duration>: Ein optionales Zeitlimit für die Bewertung. Der Standardwert ist der Wert des Flags „query.timeout“ und wird durch diesen begrenzt.limit=<number>: Eine optionale maximale Anzahl von Reihen, die zurückgegeben werden sollen. Dadurch werden Reihen für Matrizen und Vektoren gekürzt, Skalare oder Strings sind jedoch nicht betroffen. Der Wert 0 deaktiviert dieses Limit.lookback_delta=<number>: Ein optionaler Parameter, mit dem der Rückschauzeitraum speziell für diese Abfrage überschrieben wird.
Wenn der Zeitparameter weggelassen wird, wird die aktuelle Serverzeit verwendet.
Bei größeren Abfragen, die die Zeichenbeschränkung für URLs überschreiten könnten, können Sie diese Parameter mit der POST-Methode senden. Der Anfragetext muss URL-codiert sein und der Content-Type-Header muss auf „application/x-www-form-urlencoded“ festgelegt sein.
Der Datenabschnitt des Abfrageergebnisses hat das folgende Format:
{
"resultType": "matrix" | "vector" | "scalar" | "string",
"result": <value>
}
<value> bezieht sich auf die Abfrageergebnisdaten, die je nach resultType unterschiedliche Formate haben.
Im folgenden Beispiel wird der Ausdruck „up“ zum Zeitpunkt 2015-07-01T20:10:51.781Z ausgewertet:
curl 'http://localhost:9090/api/v1/query?query=up&time=2015-07-01T20:10:51.781Z'
{
"status" : "success",
"data" : {
"resultType" : "vector",
"result" : [
{
"metric" : {
"__name__" : "up",
"job" : "prometheus",
"instance" : "localhost:9090"
},
"value": [ 1435781451.781, "1" ]
},
{
"metric" : {
"__name__" : "up",
"job" : "node",
"instance" : "localhost:9100"
},
"value" : [ 1435781451.781, "0" ]
}
]
}
}
Bereichsabfragen
Der folgende Endpunkt wertet eine Ausdrucksabfrage über einen bestimmten Zeitraum aus:
GET /api/v1/query_range
POST /api/v1/query_range
Die folgenden URL-Abfrageparameter sind für Prometheus-Ausdrucksabfragen verfügbar:
query=<string>: Der Prometheus-Ausdrucksabfragestring.start=<rfc3339 | unix_timestamp>: Startzeitstempel, einschließlich.end=<rfc3339 | unix_timestamp>: Endzeitstempel (einschließlich).step=<duration | float>: Schrittweite der Abfrageauflösung im Dauerformat oder als Gleitkommazahl in Sekunden.timeout=<duration>: Ein optionales Zeitlimit für die Bewertung. Der Standardwert ist der Wert des Flags „query.timeout“ und wird durch diesen begrenzt.limit=<number>: Eine optionale maximale Anzahl von Reihen, die zurückgegeben werden sollen. Dadurch werden Reihen für Matrizen und Vektoren gekürzt, Skalare oder Strings sind jedoch nicht betroffen. Der Wert 0 deaktiviert dieses Limit.lookback_delta=<number>: Ein optionaler Parameter, mit dem der Rückschauzeitraum speziell für diese Abfrage überschrieben wird.
Bei größeren Abfragen, die die Zeichenbeschränkung für URLs überschreiten könnten, können Sie diese Parameter mit der POST-Methode senden. Der Anfragetext muss URL-codiert sein und der Content-Type-Header muss auf „application/x-www-form-urlencoded“ festgelegt sein.
Der Datenabschnitt des Abfrageergebnisses hat das folgende Format:
{
"resultType": "matrix",
"result": <value>
}
Im folgenden Beispiel wird der Ausdruck „up“ über einen Zeitraum von 30 Sekunden mit einer Abfrageauflösung von 15 Sekunden ausgewertet.
curl 'http://localhost:9090/api/v1/query_range?query=up&start=2015-07-01T20:10:30.781Z&end=2015-07-01T20:11:00.781Z&step=15s'
{
"status" : "success",
"data" : {
"resultType" : "matrix",
"result" : [
{
"metric" : {
"__name__" : "up",
"job" : "prometheus",
"instance" : "localhost:9090"
},
"values" : [
[ 1435781430.781, "1" ],
[ 1435781445.781, "1" ],
[ 1435781460.781, "1" ]
]
},
{
"metric" : {
"__name__" : "up",
"job" : "node",
"instance" : "localhost:9091"
},
"values" : [
[ 1435781430.781, "0" ],
[ 1435781445.781, "0" ],
[ 1435781460.781, "1" ]
]
}
]
}
}
Benennung von Messwerten und Labels
Richtlinien für die Benennung von Messwerten
Beachten Sie beim Definieren von Messwertnamen die folgenden Grundsätze:
Ein Messwertname SOLLTE ein aus einem Wort bestehendes Anwendungspräfix enthalten, das in Clientbibliotheken manchmal als „Namespace“ bezeichnet wird. Dieses Präfix gibt die Domain an, zu der der Messwert gehört. Bei anwendungsspezifischen Messwerten wird in der Regel der Name der Anwendung als Präfix verwendet.
Beispiele:
- prometheus_notifications_total (spezifisch für den Prometheus-Server)
- process_cpu_seconds_total (von vielen Clientbibliotheken exportiert)
- http_request_duration_seconds (für alle HTTP-Anfragen)
Ein Messwertname MUSS eine einzelne Einheit darstellen (z.B. keine Sekunden mit Millisekunden oder Sekunden mit Byte mischen).
Ein Messwertname SOLLTE Basiseinheiten (z.B. Sekunden, Byte, Meter) anstelle von abgeleiteten Einheiten (z.B. Millisekunden, Megabyte, Kilometer) verwenden.
Ein Messwertname SOLLTE ein Plural-Einheitssuffix enthalten. Für kumulierte Zählungen sollte zusätzlich zum Einheitssuffix das Suffix „total“ verwendet werden, falls zutreffend.
Beispiele:
- http_request_duration_seconds
- node_memory_usage_bytes
- http_requests_total (für eine einheitenlose kumulierte Anzahl)
- process_cpu_seconds_total (für eine kumulierte Anzahl mit Einheit)
- foobar_build_info (für einen Pseudomesswert, der Metadaten zur ausgeführten Binärdatei bereitstellt)
Ein Messwertname KANN seine Komponenten so anordnen, dass sie bei lexikografischer Sortierung bequem gruppiert werden können, sofern alle anderen Regeln eingehalten werden. Zusammengehörige Messwerte haben oft gemeinsame Namenskomponenten, die am Anfang stehen, damit sie zusammen sortiert werden.
Beispiele:
- prometheus_tsdb_head_truncations_closed_total
- prometheus_tsdb_head_truncations_established_total
- prometheus_tsdb_head_truncations_failed_total
- prometheus_tsdb_head_truncations_total
Ein Messwertname SOLLTE für alle Labeldimensionen konsistent dasselbe logische „zu messende Element“ darstellen.
Beispiele:
- Anfragedauer
- Byte Datenübertragung
- Momentane Ressourcennutzung in Prozent
Richtlinien für die Benennung von Labels
Verwenden Sie Labels, um die Merkmale des Messobjekts zu unterscheiden. Beispiel:
- Unterscheiden Sie bei den gesamten API-HTTP-Anfragen (
api_http_requests_total) nach Vorgangstyp, z. B.create,update,delete(Anfragetypen:operation="create|update|delete"). - Unterscheiden Sie bei der API-Anfragedauer in Sekunden (
api_request_duration_seconds) nach Anfragephase, z. B.extract,transform,load(Anfragephasen:stage="extract|transform|load").
Vermeiden Sie es, Labelnamen in den Messwertnamen selbst aufzunehmen, da dies zu Redundanz führt und zu Verwirrung führen kann, wenn diese Labels später aggregiert werden.