v1.metrics – Übersicht

In diesem Dokument wird beschrieben, wie Messwertdaten, die über die 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 wenn Sie die OpenTelemetry SDKs verwenden.

OpenTelemetry ist ein Google Cloud-unterstütztes Open-Source-Projekt mit Google Cloud Entwicklern, die für den Support bei der Aufnahme und Visualisierung Ihrer Telemetriedaten zuständig sind.

Best Practices

Wenn Sie Ihre Anwendungen instrumentieren, um Tracedaten an Ihr Google Cloud Projekt zu senden, empfehlen wir, einen Exporter zu verwenden, der Daten im OTLP-Format in einen Collectorschreibt. Dieser sendet dann Ihre Tracedaten an die Telemetry API. 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:

• Übersicht über instrumentierungsbasierte Collector-Beispiele.
• Übersicht über die Aufnahme von OTLP-Messwerten.

Wenn Sie keinen Collector verwenden können, können Sie eine OpenTelemetry-Bibliothek mit einem In-Process-OTLP-Exporter verwenden, um Telemetriedaten an die Telemetry API zu senden. Informationen zum direkten Exportieren von Tracedaten finden Sie unter Cloud Trace-Exporter zum 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 Collector verwenden, verwenden Sie in der Regel auch die Erweiterung googleclientauth, um sich mit Google-Anmeldedaten zu authentifizieren.

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.

OTLP-Messwerte in Cloud Monitoring

Diese Funktion unterliegt den „Bedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA‑Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Startphase.

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 den Cloud Monitoring-Messwertstrukturen zugeordnet. In diesem Abschnitt wird Folgendes beschrieben:

• Die Zuordnung zwischen OTLP-Ressourcen und überwachten Cloud Monitoring-Ressourcen.
• Die Zuordnung zwischen OTLP-Messwerten und Cloud Monitoring-Messwerten.

Zuordnung überwachter Ressourcen

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

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 die Abfrage- und Skalierbarkeitsmöglichkeiten.

Wir empfehlen, 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 der Werte für Labels in der Reihenfolge ihrer Priorität aufgeführt:

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

Zuordnung von Messwerten

Messwerte werden in das Prometheus-Zeitachsenformat konvertiert. Messwertnamen dürfen 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 durch die Konvertierung ein target_info Messwert hinzugefügt, der alle Ressourcenattribute außer service.name, service.instance.id, und service.namespace enthält.

Alle OTLP INT64 Messwerte werden in Cloud Monitoring in den DOUBLE Werttyp übersetzt, auch wenn der Collector den Werttyp als INT64 angibt. Diese Änderung wird vorgenommen, da der Werttyp einer Zeitachse in Monarch nicht geändert werden kann. Die häufigste Folge der Unterstützung von INT64-Werten sind Kollisionen, die nur durch das Löschen eines Messwerts behoben werden können.

Hinweis: Es kann zu Kollisionen bei Werttypen kommen, insbesondere wenn Sie zuvor INT64 target_info Messwerte gesendet haben. Wenn Kollisionen auftreten, besteht die beste langfristige Lösung darin, den Messwertdeskriptor für die INT64-target_info-Messwerte zu löschen. Verwenden Sie dieses Golang-Skript, um diesen Deskriptor aus Ihrem Messwertbereich zu löschen.

Zuordnung von Prometheus-Messwerten

Messwerttypen werden wie folgt zugeordnet:

• OTLP-Gauge wird Cloud Monitoring-Gauge zugeordnet.
• OTLP-Summe wird wie folgt zugeordnet:
  • Cloud Monitoring Gauge wenn is_monotonic auf false gesetzt ist.
  • Cloud Monitoring Summe wenn aggregation_temporality auf AGGREGATION_TEMPORALITY_CUMULATIVE gesetzt ist.
  • Cloud Monitoring Delta , wenn aggregation_temporality auf AGGREGATION_TEMPORALITY_DELTA gesetzt ist.
• OTLP-Histogramm wird Cloud Monitoring Verteilung mit einer Messwertart vom Typ Summe oder Delta, je nach Wert von aggregation_temporality zugeordnet.
• OTLP-Zusammenfassungsmesswerte werden in einzelne Zeitachsen für jede Komponente erweitert: count, sum und jedes quantile.
  • Die Namen für Messwerte vom Typ „Anzahl“ und „Summe“ werden mit _count oder _sum bzw. ergänzt und als kumulative Cloud Monitoring Messwerte vom Typ „DOUBLE“ geschrieben.
  • Jedes Quantil wird zu einer eigenen Gauge-Zeitachse vom Typ „DOUBLE“ mit einem quantile-Label.

In der folgenden Tabelle ist die Zuordnung von Messwerten zusammengefasst:

OTLP Punktart	Monitoring Messwertart	Monitoring Werttyp	Suffix	Hinweise
GAUGE	GAUGE	DOUBLE	/gauge
ANZEIGE (metric.metadata["prometheus.type"]="unknown")	GAUGE	DOUBLE	/unknown	Unbekannte Prometheus-Messwerte werden vom OpenTelemetry Collector in einen Zähler und eine Gauge aufgeteilt.
SUMME (monotonic, CUMULATIVE)	CUMULATIVE	DOUBLE	/counter
SUMME (monotonic, CUMULATIVE, metric.metadata["prometheus.type"]="unknown")	CUMULATIVE	DOUBLE	/unknown:counter	Unbekannte Prometheus-Messwerte werden vom OpenTelemetry Collector in einen Zähler und eine Gauge aufgeteilt.
SUMME (monotonic, DELTA)	DELTA	DOUBLE	/delta
SUMME (non-monotonic, CUMULATIVE)	GAUGE	DOUBLE	/gauge
SUMME (non-monotonic, DELTA)	Nicht unterstützt			UpDownCounters mit Delta-Temporarität werden nicht unterstützt.
HISTOGRAMM (CUMULATIVE)	CUMULATIVE	VERTEILUNG mit expliziten Buckets	/histogram
EXPONENTIAL HISTOGRAMM (CUMULATIVE)	CUMULATIVE	VERTEILUNG mit exponentiellen Buckets	/histogram
HISTOGRAMM (DELTA)	DELTA	VERTEILUNG mit expliziten Buckets	/histogram:delta
EXPONENTIAL HISTOGRAMM (DELTA)	DELTA	VERTEILUNG mit exponentiellen Buckets	/histogram:delta
ZUSAMMENFASSUNG (sum, count, quantile)	CUMULATIVE CUMULATIVE ANZEIGE	DOUBLE DOUBLE DOUBLE	_sum/summary:counter _count/summary /summary	Zusammenfassungsdatenpunkte werden als mehrere Zeitachsen geschrieben, eine für Anzahl, Summe und jedes berechnete Quantil. Quantilmesswerte werden auch mit einem quantile Label generiert.

Unterschiede zwischen dem googlemanagedprometheus-Exporter und der Telemetry API

Die Telemetry API (telemetry.googleapis.com) verarbeitet Messwerte anders als der googlemanagedprometheus Exporter:

• Die Telemetry API erlaubt Punkte (.) und Schrägstriche (/) in Messwertnamen. Der googlemanagedprometheus-Exporter konvertiert alle Instanzen dieser Zeichen in Unterstriche (_). Ein OTLP-Messwert mit dem Namen 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 basierend auf den Namen. Der Unterschied in der Verarbeitung von Punkten (.) und Schrägstrichen (/) durch die Aufnahmepfade führt dazu, dass sich die resultierenden Messwertdeskriptoren zwischen Messwerten, die mit dem googlemanagedprometheus Exporter aufgenommen wurden, und solchen, die mit dem otlphttp Exporter aufgenommen wurden, unterscheiden. Wenn Sie beide Aufnahmepfade verwenden, haben Sie zwei Messwertgruppen. Um bei Abfragen vollständige Ergebnisse zu erhalten, müssen Sie die Ergebnisse aus den Prometheus- und OTLP-Versionen der Messwerte manuell zusammenführen.

• Die Telemetry API hängt einer Messwertbezeichnung keine Einheit an, wenn eine Einheit vorhanden ist, und sie hängt kein _total-Suffix an Zähler an. Ein Messwert, der mit 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 Wert sum_of_squared_deviation für Verteilungswerte, die aus exponentiellen Histogrammen abgeleitet wurden. Der googlemanagedprometheus-Exporter legt dieses Feld für exponentielle Histogramme nicht fest.

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

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

Cloud Monitoring und Datenresidenz

Informationen dazu, wie Ihre Messwertdaten gespeichert werden, finden Sie unter Datenregionalität für Cloud Monitoring.

Aufgenommene Daten ansehen

Über die Telemetry API aufgenommene Messwertdaten können auf der Seite Metrics Explorer angezeigt werden. Informationen zum Ansehen und Darstellen Ihrer Messwertdaten in Diagrammen finden Sie unter Diagramme mit dem Metrics Explorer erstellen.