Messwerte abfragen und aufrufen

Nachdem Sie Messwerte aus Ihren bereitgestellten Arbeitslasten in Google Distributed Cloud (GDC) Air-Gapped erfasst haben, können Sie mit der Analyse beginnen. Zum Analysieren von Messwerten können Sie sie in informativen Grafana-Dashboards visualisieren und filtern oder mit dem curl-Tool direkt über Cortex darauf zugreifen, um sie flexibel zu scripten und zu automatisieren.

Auf dieser Seite finden Sie eine detaillierte Anleitung zum Abfragen und Visualisieren Ihrer Messwerte über die Grafana-Benutzeroberfläche und das curl-Tool für den Cortex-Endpunkt, um Einblicke in die Leistung Ihrer Arbeitslast zu erhalten.

Sie haben zwei Möglichkeiten, auf Ihre Messwerte zuzugreifen:

  • Grafana-Dashboards: Mit intuitiven Visualisierungen von wichtigen Messwerten wie CPU-Auslastung, Speicherverbrauch und Netzwerkaktivität können Sie Trends analysieren und Anomalien erkennen. Grafana bietet eine benutzerfreundliche Oberfläche zum Filtern und Analysieren Ihrer Workload-Daten in Dashboards.
  • Cortex-Endpunkt: Für komplexere Anwendungsfälle können Sie die Cortex-Instanz Ihres Projekts direkt über das Tool curl in einer Befehlszeile abfragen. In Cortex werden die Prometheus-Messwerte Ihres Projekts gespeichert und ein HTTP-Endpunkt für den programmatischen Zugriff bereitgestellt. Mit diesem Zugriff können Sie Daten exportieren, Aufgaben automatisieren und benutzerdefinierte Integrationen erstellen.

Hinweise

Bitten Sie den IAM-Administrator Ihrer Organisation oder Ihres Projekts, 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 erforderlichem Zugriff und den erforderlichen Berechtigungen können Sie Grafana-Rollen in einer Organisation oder einem Projekt erhalten.

Alternativ können Sie Ihren Projekt-IAM-Administrator bitten, Ihnen die Rolle „Project Cortex Prometheus Viewer“ in Ihrem Projekt-Namespace zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Abfragen von Messwerten über den Cortex-Endpunkt benötigen.

In der folgenden Tabelle sind die Role-Anforderungen für PA persona 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

Ersetzen Sie die folgenden Variablen entsprechend:

Variable Beschreibung
KUBECONFIG Sie benötigen die kubeconfig für den jeweiligen Cluster, der den NAMESPACE enthält, auf den dieses 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 dieses RoleBinding erstellt und angewendet wird. Suchen Sie in der vorherigen Tabelle nach der Spalte Namespace.
EMAIL_ADDRESS Die Kennung des Nutzers, dem die Rolle zugewiesen wird. Das ist oft 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. Nach den in der vorherigen Tabelle verfügbaren Rollen suchen
GROUP_NAME Der Name der Role, die die Berechtigungen enthält, die Sie dem Nutzer gewähren möchten. Beispiel: io-group.
ZONE Name der Zone

Konfiguration 1

Diese Konfiguration ist für die Persona PA und zielt auf das Objekt grafana im Cluster org-admin ab. Damit wird einem Group die Rolle project-grafana-viewer im Namespace platform-obs zugewiesen.

  • Kubectl-Befehl

    So sieht das generische Befehlsformat aus:

    kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --group=`GROUP_NAME` --role=project-grafana-viewer

    Beispiel:

    kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --group=my-team --namespace=platform-obs

  • IAC-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

Diese Konfiguration ist für die Persona PA und zielt auf das Objekt cortex im Cluster org-admin ab. Damit wird einem Group die Rolle project-cortex-prometheus-viewer im Namespace platform-obs zugewiesen.

  • Kubectl-Befehl

    So sieht das generische Befehlsformat aus:

    kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --group=`GROUP_NAME` --role=project-cortex-prometheus-viewer

    Beispiel:

    kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-cortex-prometheus-viewer-binding --role=project-cortex-prometheus-viewer --group=my-team --namespace=platform-obs

  • IAC-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

Diese Konfiguration ist für die Persona PA und zielt auf das Objekt grafana im Cluster org-admin ab. Damit wird einem User die Rolle project-grafana-viewer im Namespace platform-obs zugewiesen.

  • Kubectl-Befehl

    So sieht das generische Befehlsformat aus:

    kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --user=`EMAIL_ADDRESS` --role=project-grafana-viewer

    Beispiel:

    kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --user=my-email@example.com --namespace=platform-obs

  • IAC-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

Diese Konfiguration ist für die Persona PA und zielt auf das Objekt cortex im Cluster org-admin ab. Damit wird einem User die Rolle project-cortex-prometheus-viewer im Namespace platform-obs zugewiesen.

  • Kubectl-Befehl

    So sieht das generische Befehlsformat aus:

    kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --user=`EMAIL_ADDRESS` --role=project-cortex-prometheus-viewer

    Beispiel:

    kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-cortex-prometheus-viewer-binding --role=project-cortex-prometheus-viewer --user=my-email@example.com --namespace=platform-obs

  • IAC-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 den Arbeitslasten Ihres Projekts zu filtern:

Grafana-Dashboards

In diesem Abschnitt wird beschrieben, wie Sie mit Grafana-Dashboards auf Ihre Messwerte zugreifen.

Grafana-Endpunkt ermitteln

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-obs in der Organisation org-1 ist beispielsweise https://org-1/platform-obs/grafana.

Messwerte in der Grafana-Benutzeroberfläche ansehen

Messwerte über die Grafana-Benutzeroberfläche abrufen:

  1. Wählen Sie in der GDC Console Ihr Projekt aus.
  2. Wählen Sie im Navigationsmenü Vorgänge > Monitoring aus.

  3. Klicken Sie auf Alle in Grafana ansehen.

    Eine neue Seite mit Ihrem Grafana-Endpunkt wird geöffnet und die Benutzeroberfläche wird angezeigt.

  4. Klicken Sie in der Benutzeroberfläche im Navigationsmenü auf Expl. Datenanalyse Explore, um die Seite Explore zu öffnen.

  5. Wählen Sie im Menü in der Leiste Explore eine Datenquelle aus, um Messwerte abzurufen. Das hängt von Ihrem Universumstyp ab:

    • Universen mit einer Zone: Wählen Sie prometheus aus, um Messwerte aus der einzelnen Zone Ihres Universums aufzurufen.

    • 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 aufzurufen, unabhängig davon, in welcher Zone Sie angemeldet sind.

      Wenn Sie außerdem zonenübergreifende Datenvisualisierungen in einem einzigen Dashboard erstellen und Ihrer Abfrage mehrere Zonen hinzufügen möchten, wählen Sie Gemischt als Datenquelle aus.

  6. Geben Sie eine Abfrage ein, um mit PromQL-Ausdrücken (Prometheus Query Language) nach Messwerten zu suchen. Sie können diesen Schritt auf eine der beiden folgenden Arten ausführen:

    • Wählen Sie in den Menüs Messwert und Label-Filter einen Messwert und ein Label für Ihre Abfrage aus. Klicken Sie auf Hinzufügen Hinzufügen, um weitere Labels hinzuzufügen. Klicken Sie dann auf Abfrage ausführen.
    • Geben Sie die 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.

    Die Option „Prometheus“ ist auf der Seite „Explore“ ausgewählt, um Messwerte abzurufen.

    Abbildung 1. Menüoption zum Abfragen von Messwerten über die Grafana-Benutzeroberfläche.

    In Abbildung 1 wird mit der Option prometheus die Benutzeroberfläche angezeigt, über die Sie Abfragen in Grafana erstellen können, um Messwerte abzurufen.

    Beispiele für Werte von Labels, mit denen Sie Messwerte abfragen können, finden Sie unter Beispielabfragen und ‑labels.

Cortex-Endpunkt

In diesem Abschnitt wird beschrieben, wie Sie mit Cortex auf Ihre Messwerte zugreifen.

Cortex-Endpunkt ermitteln

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-obs in der Organisation org-1 ist beispielsweise https://org-1/platform-obs/cortex/prometheus/.

curl-Anfrage authentifizieren

  1. Laden Sie die gcloud CLI herunter und installieren Sie sie.

  2. Legen Sie das gdcloud-Attribut core/organization_console_url fest.

    gdcloud config set core/organization_console_url
https://GDC_URL

  3. Mit dem konfigurierten Identitätsanbieter anmelden:

    gdcloud auth login

  4. Authentifizieren Sie sich mit Ihrem Nutzernamen und Passwort und melden Sie sich an.

    Wenn die Anmeldung erfolgreich ist, können Sie den Autorisierungsheader in Ihrer curl-Anfrage über den Befehl gdcloud auth print-identity-token verwenden. Weitere Informationen finden Sie unter gdcloud auth.

Cortex-Endpunkt aufrufen

Führen Sie die folgenden Schritte aus, um den Cortex-Endpunkt mit dem Tool curl zu erreichen:

  1. Authentifizieren Sie die curl-Anfrage.

  2. Verwenden 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 hat das JSON-Format.

Beispielabfragen und ‑labels

Sie können Messwerte anhand des Messwertnamens und von Schlüssel/Wert-Paaren 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 dafür sorgen, dass für ihre Arbeitslasten Messwerte generiert werden, und Tags hinzufügen, um diese Messwerte zu filtern.

Sie können beispielsweise einen api_http_requests_total-Messwert 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 annehmen kann. Daher erstellen Sie für jeden Anfragetyp, den Sie möglicherweise erhalten, drei Messwertstreams. In diesem Fall führen Sie die folgende Abfrage aus, um die Anzahl der HTTP-Anfragen GET zu ermitteln:

api_http_requests_total{request_method="GET"}

Weitere Informationen zu Messwerten und Labels finden Sie unter Messwerte und Label-Benennung.

Im Folgenden finden Sie einige der Standardlabels, die durch die benutzerdefinierte Ressource MonitoringTarget hinzugefügt werden. Sie können diese Standardlabels verwenden, um Messwerte abzufragen:

  • _gdch_service: der Kurzname des Dienstes.
  • cluster ist 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:

Standardlabels
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/J

I und J sind eindeutige Zahlen, die intern festgelegt werden, um Namenskonflikte zu vermeiden.
instance Die $IP:$PORT des eingestellten Dienstes. Wenn eine Arbeitslastressource mehrere Replikate hat, können Sie sie mit diesem Feld unterscheiden.

In den folgenden Codebeispielen sehen Sie, wie Sie Schlüssel/Wert-Paare für Labels verwenden, um verschiedene Messwerte abzufragen:

  • Alle Messwertstreams der verarbeiteten Vorgänge in Ihrem Projekt ansehen:

    processed_ops_total

  • So sehen Sie die verarbeiteten Vorgänge, die in einem Kubernetes-Cluster erfasst wurden:

    processed_ops_total{cluster="CLUSTER_NAME"}

  • So sehen Sie die in einem Kubernetes-Cluster erfasste CPU-Auslastung:

    cpu_usage{cluster="CLUSTER_NAME"}

Mit dem Tool zum Neulabeln von Messwerten können Sie Labels hinzufügen, die anfangs nicht von den erfassten Containern bereitgestellt wurden, und erstellte Messwerte umbenennen. Sie müssen die benutzerdefinierte MonitoringTarget-Ressource konfigurieren, um den von ihr erfassten Messwerten Labels hinzuzufügen. Geben Sie diese Labels im Feld metricsRelabelings der benutzerdefinierten Ressource an. Weitere Informationen finden Sie unter Label-Messwerte.

HTTP API abfragen

Formatübersicht

Die API-Antworten sind immer im JSON-Format. Bei erfolgreichen Anfragen wird immer ein 2xx-Statuscode zurückgegeben.

Bei ungültigen Anfragen geben die API-Handler ein JSON-Fehlerobjekt zusammen mit einem der folgenden HTTP-Statuscodes zurück:

  • 400 Bad Request: Wenn wichtige Parameter fehlen oder falsch angegeben wurden.
  • 503 Service Unavailable: Wenn Abfragen ihr Zeitlimit überschreiten oder abgebrochen werden.

Alle Daten, die erfolgreich erhoben wurden, werden im Feld „data“ der Antwort angegeben.

Das Format des JSON-Antwortumschlags 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>"]
}

Sofortige Abfragen

Mit dem folgenden Endpunkt wird eine Sofortabfrage zu einem bestimmten Zeitpunkt ausgewertet:

GET /api/v1/query
POST /api/v1/query

Die folgenden URL-Abfrageparameter sind für Prometheus-Ausdrucksabfragen verfügbar:

  • query=<string>: Der Prometheus-Ausdrucks-Abfragestring.
  • time=<rfc3339 | unix_timestamp>: Ein optionaler Zeitstempel für die Auswertung, 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 Auswertung. Der Standardwert entspricht dem Wert des Flags „query.timeout“ und ist durch diesen Wert begrenzt.
  • limit=<number>: Eine optionale maximale Anzahl der zurückzugebenden Serien. Dadurch werden Reihen für Matrizen und Vektoren gekürzt, Skalare oder Strings sind davon jedoch nicht betroffen. Bei einem Wert von 0 wird dieses Limit deaktiviert.
  • lookback_delta=<number>: Ein optionaler Parameter, mit dem der Rückblickzeitraum speziell für diese Abfrage überschrieben werden kann.

Wenn der Zeitparameter weggelassen wird, wird die aktuelle Serverzeit verwendet.

Bei größeren Anfragen, die die Zeichenbeschränkungen 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“ gesetzt sein.

Der Datenabschnitt des Abfrageergebnisses hat das folgende Format:

{
  "resultType": "matrix" | "vector" | "scalar" | "string",
  "result": <value>
}

<value> bezieht sich auf die Daten des Abfrageergebnisses, die je nach „resultType“ unterschiedliche Formate haben.

Im folgenden Beispiel wird der Ausdruck bis 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 Zeitraum hinweg 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-Ausdrucks-Abfragestring.
  • 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 Auswertung. Der Standardwert entspricht dem Wert des Flags „query.timeout“ und ist durch diesen Wert begrenzt.
  • limit=<number>: Eine optionale maximale Anzahl der zurückzugebenden Serien. Dadurch werden Reihen für Matrizen und Vektoren gekürzt, Skalare oder Strings sind davon jedoch nicht betroffen. Bei einem Wert von 0 wird dieses Limit deaktiviert.
  • lookback_delta=<number>: Ein optionaler Parameter, mit dem der Rückblickzeitraum speziell für diese Abfrage überschrieben werden kann.

Bei größeren Anfragen, die die Zeichenbeschränkungen 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“ gesetzt 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" ]
            ]
         }
      ]
   }
}

Messwerte und Label benennen

Richtlinien zur Benennung von Messwerten

Beachten Sie beim Definieren von Messwertnamen die folgenden Grundsätze:

  • Ein Messwertname SOLLTE ein Anwendungspräfix aus einem Wort 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 repräsentieren. Vermeiden Sie es beispielsweise, Sekunden mit Millisekunden oder Sekunden mit Byte zu mischen.

  • Für einen Messwertnamen SOLLTEN Basiseinheiten (z.B. Sekunden, Byte, Meter) anstelle von abgeleiteten Einheiten (z.B. Millisekunden, Megabyte, Kilometer) verwendet werden.

  • Ein Messwertname SOLLTE ein Suffix für die Pluraleinheit enthalten. Bei kumulativen Zählungen sollte zusätzlich zum Einheitssuffix das Suffix „total“ verwendet werden, sofern zutreffend.

    Beispiele:

    • http_request_duration_seconds
    • node_memory_usage_bytes
    • http_requests_total (für eine einheitenlose kumulative Anzahl)
    • process_cpu_seconds_total (für einen kumulativen Zähler mit Einheit)
    • foobar_build_info (für eine Pseudomessung, die Metadaten zur laufenden Binärdatei bereitstellt)

  • Bei einem Messwertnamen DÜRFEN die Komponenten so angeordnet werden, dass eine bequeme Gruppierung bei lexikografischer Sortierung möglich ist, sofern alle anderen Regeln eingehalten werden. Zugehörige Messwerte haben oft gemeinsame Namensbestandteile, die zuerst platziert werden, 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 über alle Labeldimensionen hinweg konsistent dasselbe logische „zu messende Element“ darstellen.

    Beispiele:

    • Anfragedauer
    • Byteanzahl der Datenübertragung
    • Momentane Ressourcennutzung als Prozentsatz

Richtlinien für die Benennung von Labels

Verwenden Sie Labels, um die Merkmale eines Messobjekts zu unterscheiden. Beispiel:

  • Bei den gesamten API-HTTP-Anfragen (api_http_requests_total) wird nach Vorgangstyp unterschieden, z. B. create, update, delete (Anfragetypen: operation="create|update|delete").
  • Bei der Dauer von API-Anfragen in Sekunden (api_request_duration_seconds) wird nach Anfragephase unterschieden, 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 zusammengefasst werden.