v1.metrics – Übersicht

In diesem Dokument wird beschrieben, wie Messwertdaten, die mit der Telemetry (OTLP) API an Ihr Google Cloud Projekt gesendet werden, den Cloud Monitoring-Strukturen zugeordnet werden. Diese API implementiert das OpenTelemetry Line Protocol. Sie können Daten an diese API senden, wenn Sie Ihre Anwendungen mit einem otlphttp-Exporter und einem OpenTelemetry Collector instrumentieren oder die OpenTelemetry SDKs verwenden.

OpenTelemetry ist ein von Google Cloudunterstütztes Open-Source-Projekt mit Google CloudTechnikern, die dafür sorgen, dass Ihre Telemetriedaten aufgenommen und visualisiert werden können.

Best Practices

Wenn Sie Ihre Anwendungen instrumentieren, um Tracedaten an IhrGoogle Cloud -Projekt zu senden, empfehlen wir, einen Exporter zu verwenden, der OTLP-formatierte Daten in einen Collector schreibt, der dann Ihre Tracedaten an die Telemetry API sendet. Geben Sie in Ihrem Collector nur die Stamm-URL an:

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

OpenTelemetry erkennt den Datentyp und hängt automatisch /v1/traces, /v1/metrics oder /v1/logs an. Weitere Informationen finden Sie unter OTLP/HTTP-Anfrage.

Beispiele für den Export von Trace- oder Messwertdaten in die Telemetry API finden Sie in den folgenden Dokumenten:

Wenn Sie keinen Collector verwenden können, können Sie eine OpenTelemetry-Bibliothek mit einem In-Process-OTLP-Exporter verwenden, um Telemetrie an die Telemetry API zu senden. Informationen zum direkten Exportieren von Trace-Daten finden Sie unter Cloud Trace-Exporter für den OTLP-Endpunkt.

Authentifizierung

Sie müssen Ihre Exporter mit den Anmeldedaten konfigurieren, die zum Senden von Daten an Ihr Google Cloud -Projekt erforderlich sind. Wenn Sie beispielsweise Collectors verwenden, authentifizieren Sie sich in der Regel mit der Erweiterung googleclientauth mit Google-Anmeldedaten.

Ein Beispiel für die Authentifizierung bei Verwendung des direkten Exports von Tracedaten finden Sie unter Authentifizierung konfigurieren. In diesem Beispiel wird veranschaulicht, wie Sie den Exporter mit Ihren Google Cloud Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) konfigurieren und Ihrer Anwendung eine sprachspezifische Google Auth-Bibliothek hinzufügen.

Wenn Sie Telemetriedaten mit der Telemetry API an Ihr Google Cloud -Projekt senden möchten, müssen Sie außerdem Folgendes tun:

  • Kontingentprojekt konfigurieren Weitere Informationen finden Sie unter Kontingentprojekt festlegen.
  • Weisen Sie dem Nutzer oder dem Dienstkonto, das von der Anwendung verwendet wird, die Rolle Service Usage-Nutzer (roles/serviceusage.serviceUsageConsumer) für dieses Kontingentprojekt zu.

  • Weisen Sie dem Nutzer oder dem Dienstkonto, das von der Anwendung verwendet wird, die folgenden Rollen für Ihr Projekt zu:

OTLP-Messwerte in Cloud Monitoring

Wenn Messwerte mit einem OpenTelemetry Collector und dem otlphttp-Exporter in Cloud Monitoring aufgenommen oder direkt mit einem OpenTelemetry SDK gesendet werden, werden die OTLP-Messwerte Cloud Monitoring-Messwertstrukturen zugeordnet. In diesem Abschnitt wird Folgendes beschrieben:

Zuordnung überwachter Ressourcen

Alle Messwertpunkte werden mit der Prometheus-Zuordnung so geschrieben, wie sie für Google Cloud Managed Service for Prometheus sind.

Prometheus-Zuordnung

Für Prometheus-Messwerte muss der überwachte Ressourcentyp prometheus_target verwendet werden.

Die folgenden Labels für den Ressourcentyp prometheus_target werden verwendet, um Daten in Monarch zu schematisieren und effizient zu speichern. Je genauer Sie Werte für diese Attribute angeben, desto besser sind Abfragefähigkeit und Skalierbarkeit.

Wir empfehlen dringend, beim Festlegen von Werten für diese Labels so explizit wie möglich zu sein. Wir haben jedoch eine Fallback-Logik implementiert, die verwendet wird, wenn keine expliziten Werte vorhanden sind.

In der folgenden Tabelle sind die Quellen für Werte für Labels nach Priorität aufgeführt:

prometheus-target-Label Verwendeter Wert (in Prioritätsreihenfolge)
location (erforderlich)
  • Attribut location
  • Attribut cloud.availability_zone
  • Attribut cloud.region
  • Punkt ablehnen, wenn leer
cluster
  • Attribut cluster
  • Attribut k8s.cluster.name
  • __gce__, wenn das Attribut cloud.platform gcp_compute_engine ist
  • __run__, wenn das Attribut cloud.platform gcp_cloud_run ist
  • Leerer String
namespace
  • Attribut namespace
  • Attribut k8s.namespace.name
  • Attribut service.namespace
  • Leerer String
job
  • Attribut job
  • "service.namespace" + „/“ + service.namespace-Attribut
  • Attribut service.name
  • service.name-Attribut, sofern nicht unknown_service:foo
  • Attribut faas.name
  • Attribut k8s.deployment.name
  • Attribut k8s.statefulset.name
  • Attribut k8s.job.name
  • Attribut k8s.cronjob.name
  • Attribut service.name, wenn unknown_service:foo
  • Leerer String
instance (erforderlich)
  • Attribut instance
  • Attribut service.instance.id
  • Attribut faas.instance
  • Attribut k8s.pod.name:k8s.container.name
  • k8s.pod.name-Attribut, wenn kein Containername vorhanden ist
  • Attribut host.id
  • Punkt ablehnen, wenn leer

Messwertzuordnung

Messwerte werden in das Prometheus-Zeitreihenformat konvertiert. Messwertnamen dürfen entweder keine Domain oder die Domain prometheus.googleapis.com haben. Nach der Konvertierung enthält der Messwertname das Präfix prometheus.googleapis.com und ein zusätzliches Suffix, das auf der OTLP-Punktart basiert. Der resultierende Cloud Monitoring-Messwert hat die folgende Struktur:

prometheus.googleapis.com/{metric_name}/{suffix}

Außerdem wird für jede eindeutige OpenTelemetry-Ressource der Messwert target_info hinzugefügt, der alle Ressourcenattribute mit Ausnahme von service.name, service.instance.id und service.namespace enthält.

Alle OTLP-Messwerte vom Typ INT64 werden in Cloud Monitoring in den Werttyp DOUBLE übersetzt, auch wenn der Collector den Werttyp als INT64 angibt. Diese Änderung wird vorgenommen, da der Werttyp nicht geändert werden kann, sobald sich eine Zeitreihe in Monarch befindet. Die häufigste Folge der Unterstützung von INT64-Werten ist, dass es zu Konflikten kommt, die nur durch das Löschen eines Messwerts behoben werden können.

Zuordnung von Prometheus-Messwerten

Messwerttypen werden so zugeordnet:

  • OTLP-Messgeräte werden Cloud Monitoring-Messgeräten zugeordnet.
  • OTLP-Summen werden so zugeordnet:
    • Cloud Monitoring-Messgerät, wenn is_monotonic auf false festgelegt ist.
    • In Cloud Monitoring kumulativ, wenn aggregation_temporality auf AGGREGATION_TEMPORALITY_CUMULATIVE festgelegt ist.
    • Zu Cloud Monitoring delta, wenn aggregation_temporality auf AGGREGATION_TEMPORALITY_DELTA festgelegt ist.
  • OTLP-Histogramm wird Cloud Monitoring-Verteilung mit dem Messwerttyp kumulativ oder Delta zugeordnet, je nach Wert von aggregation_temporality.
  • OTLP-Zusammenfassungsmesswerte werden in einzelne Zeitreihen für jede Komponente aufgeschlüsselt: count, sum und jede quantile.
    • Die Namen für Zähl- und Summenmesswerte haben das Suffix _count bzw. _sum und werden als kumulative Cloud Monitoring-Messwerte vom Typ DOUBLE geschrieben.
    • Jedes Quantil wird zu einer eigenen Messwert-Zeitreihe vom Typ DOUBLE mit dem Label quantile.

Die folgende Tabelle fasst die Messwertzuordnung zusammen:

OTLP-Punktart Monitoring metric kind Werttyp überwachen Suffix Hinweise
ANZEIGE ANZEIGE DOUBLE /gauge  
GAUGE (metric.metadata["prometheus.type"]="unknown") ANZEIGE DOUBLE /unknown „Prometheus Unknowns“ werden vom OpenTelemetry Collector in einen Zähler und einen Messwert aufgeteilt.
SUMME (monoton, CUMULATIVE) CUMULATIVE DOUBLE /counter  
SUM (monotonic, CUMULATIVE, metric.metadata["prometheus.type"]="unknown") CUMULATIVE DOUBLE /unknown:counter „Prometheus Unknowns“ werden vom OpenTelemetry Collector in einen Zähler und einen Messwert aufgeteilt.
SUMME (monoton, DELTA) DELTA DOUBLE /delta  
SUMME (nicht monoton, CUMULATIVE) ANZEIGE DOUBLE /gauge  
SUMME (nicht monoton, DELTA) Nicht unterstützt UpDownCounters mit Delta-Temporality werden nicht unterstützt.
HISTOGRAMM (KUMULATIV) CUMULATIVE VERTEILUNG mit expliziten Buckets /histogram  
EXPONENTIELLES HISTOGRAMM (KUMULATIV) CUMULATIVE VERTEILUNG mit exponentiellen Buckets /histogram  
HISTOGRAMM (DELTA) DELTA VERTEILUNG mit expliziten Buckets /histogram:delta  
EXPONENTIELLES HISTOGRAMM (DELTA) DELTA VERTEILUNG mit exponentiellen Buckets /histogram:delta  
SUMMARY
(sum,
count,
quantile)		  
CUMULATIVE
CUMULATIVE
GAUGE		  
DOUBLE
DOUBLE
DOUBLE		  
_sum/summary:counter
_count/summary
/summary		 Zusammenfassungsdatenpunkte werden als mehrere Zeitreihen geschrieben, eine für die Anzahl, die Summe und jedes berechnete Quantil. Quantilmesswerte werden auch mit dem Label quantile generiert.

Unterschiede zwischen dem googlemanagedprometheus-Exporter und der Telemetry API

In der Telemetry API (telemetry.googleapis.com) werden Messwerte anders als im googlemanagedprometheus-Exporter verarbeitet:

  • Die Telemetry API erlaubt die Verwendung von Punkten (.) und Schrägstrichen (/) in Messwertnamen. Beim Exportieren mit googlemanagedprometheus werden alle Instanzen dieser Zeichen in den Unterstrich (_) umgewandelt. Ein OTLP-Messwert namens prometheus.googleapis.com/foo.bar/gauge wird beispielsweise vom OTLP-Exporter unverändert exportiert, vom googlemanagedprometheus-Exporter jedoch als prometheus.googleapis.com/foo_bar/gauge.

    Wenn die Messwerte aufgenommen werden, erstellt Cloud Monitoring Messwertdeskriptoren auf Grundlage der Namen. Aufgrund der unterschiedlichen Verarbeitung von Punkt (.) und Schrägstrich (/) durch die Erfassungspfade unterscheiden sich die resultierenden Messwertdeskriptoren zwischen Messwerten, die mit dem googlemanagedprometheus-Exporter erfasst werden, und Messwerten, die mit dem otlphttp-Exporter erfasst werden. Wenn Sie beide Erfassungspfade verwenden, haben Sie zwei Messwertgruppen. Wenn Sie Abfragen ausführen, müssen Sie die Ergebnisse der Prometheus- und OTLP-Versionen der Messwerte manuell zusammenführen, um vollständige Ergebnisse zu erhalten.

  • Bei der Telemetry API wird kein Suffix an einen Messwertnamen angehängt, wenn eine Einheit vorhanden ist, und es wird kein _total-Suffix an Zähler angehängt. Ein Messwert, der bei Verwendung der Telemetry API als prometheus.googleapis.com/foo/counter exportiert wird, wird vom googlemanagedprometheus-Exporter als prometheus.googleapis.com/foo_seconds_total/counter exportiert. Dieser Unterschied gilt auch für die Suffixe _total und _ratio.

  • Die API synthetisiert den sum_of_squared_deviation-Wert für Verteilungswerte, die aus exponentiellen Histogrammen abgeleitet werden. Der googlemanagedprometheus-Exporter legt dieses Feld für exponentielle Histogramme nicht fest.

  • Die API konvertiert alle Ganzzahlwerte in Double-Werte für Prometheus-Messwerte.

  • Die API legt die Labels scope_version oder scope_name nicht fest, wenn diese Labels leere Werte haben.

Cloud Monitoring und Datenstandort

Informationen dazu, wie Ihre Messwertdaten gespeichert werden, finden Sie unter Regionale Daten für Cloud Monitoring.

Wo kann ich aufgenommene Daten ansehen?

Messwertdaten, die über die Telemetry API aufgenommen werden, können auf der Seite Metrics Explorer aufgerufen werden. Informationen zum Ansehen und Darstellen Ihrer Messwertdaten finden Sie unter Diagramme mit dem Metrics Explorer erstellen.