v1.metrics – Übersicht

In diesem Dokument wird beschrieben, wie Messwertdaten, die mit der Telemetry (OTLP) API an your Google Cloud project gesendet werden, den Cloud Monitoring-Strukturen zugeordnet werden. Diese API implementiert das OpenTelemetry-Protokoll. 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 Google Cloud-unterstütztes Open-Source-Projekt, bei dem Google Cloud Entwickler dafür sorgen, dass Ihre Telemetriedaten aufgenommen und visualisiert werden können.

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 die Tracedaten dann an die Telemetry API. Geben Sie im Collector nur die Stamm-URL an:

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

OpenTelemetry erkennt den Datentyp und fügt 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 OTLP-Aufnahme.

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, authentifizieren Sie sich in der Regel mit der Erweiterung googleclientauth mit Google-Anmeldedaten.

Ein Beispiel für die Authentifizierung beim direkten Export von Tracedaten finden Sie unter Authentifizierung konfigurieren. In diesem Beispiel wird gezeigt, 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:

• Ein Kontingentprojekt konfigurieren. Weitere Informationen finden Sie unter Kontingentprojekt festlegen.

• Weisen Sie dem Nutzer oder dem Dienstkonto, das von der Anwendung verwendet wird, die folgenden IAM-Rollen (Identity and Access Management) zu:

  • Rolle „Service Usage Consumer“ (roles/serviceusage.serviceUsageConsumer) für das Kontingentprojekt.
  • Rolle „Cloud Telemetry Writer“ (roles/telemetry.writer) für das Projekt. Mit dieser Rolle kann Ihre Anwendung Log-, Messwert- und Tracedaten schreiben.

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 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 wie für Google Cloud Managed Service for Prometheus geschrieben, wobei die Prometheus-Zuordnung verwendet wird.

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 Skalierbarkeit.

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 den Wert gcp_compute_engine hat __run__, wenn das Attribut cloud.platform den Wert gcp_cloud_run hat __vae__, wenn das Attribut cloud.platform den Wert gcp.agent_engine hat 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

Messwertzuordnung

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 nicht geändert werden kann, sobald sich eine Zeitachse in Monarch befindet. 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-Messwerte vom Typ „Gauge“ werden Cloud Monitoring-Messwerten vom Typ „Gauge“ zugeordnet.
• OTLP-Messwerte vom Typ „Sum“ werden wie folgt zugeordnet:
  • Cloud Monitoring Messwerten vom Typ „Gauge“ wenn is_monotonic auf false gesetzt ist.
  • Cloud Monitoring-Messwerten vom Typ „Cumulative“ wenn aggregation_temporality auf AGGREGATION_TEMPORALITY_CUMULATIVE gesetzt ist.
  • Cloud Monitoring-Messwerten vom Typ Delta , wenn aggregation_temporality auf AGGREGATION_TEMPORALITY_DELTA gesetzt ist.
• OTLP-Messwerte vom Typ „Histogram“ werden Cloud Monitoring Messwerten vom Typ „Distribution“ mit der Messwertart „Cumulative“ oder „Delta“, je nach Wert von aggregation_temporality zugeordnet.
• OTLP-Messwerte vom Typ „Summary“ werden in einzelne Zeitachsen für jede Komponente erweitert: count, sum und jedes quantile.
  • Die Namen für Messwerte vom Typ „Count“ und „Sum“ werden mit _count oder _sum bzw. ergänzt und als kumulative Cloud Monitoring Messwerte vom Typ DOUBLEgeschrieben.
  • Jedes Quantil wird zu einer eigenen Gauge-Zeitachse vom Typ DOUBLE mit dem Label quantile.

In der folgenden Tabelle ist die Messwertzuordnung 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 einen Messwert vom Typ „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 einen Messwert vom Typ „Gauge“ aufgeteilt.
SUMME (monotonic, DELTA)	DELTA	DOUBLE	/delta
SUMME (non-monotonic, CUMULATIVE)	GAUGE	DOUBLE	/gauge
SUMME (non-monotonic, DELTA)	Nicht unterstützt			UpDown-Zähler mit Delta-Temporality werden nicht unterstützt.
HISTOGRAM (CUMULATIVE)	CUMULATIVE	DISTRIBUTION mit expliziten Buckets	/histogram
EXPONENTIAL HISTOGRAM (CUMULATIVE)	CUMULATIVE	DISTRIBUTION mit exponentiellen Buckets	/histogram
HISTOGRAM (DELTA)	DELTA	DISTRIBUTION mit expliziten Buckets	/histogram:delta
EXPONENTIAL HISTOGRAM (DELTA)	DELTA	DISTRIBUTION mit exponentiellen Buckets	/histogram:delta
SUMMARY (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 auf Grundlage der Namen. Aufgrund der unterschiedlichen Verarbeitung von Punkten (.) und Schrägstrichen (/) durch die Aufnahmepfade unterscheiden sich die resultierenden Messwertdeskriptoren zwischen Messwerten, die mit dem googlemanagedprometheus-Exporter aufgenommen wurden, und solchen, die mit dem otlphttp-Exporter aufgenommen wurden. Wenn Sie beide Aufnahmepfade verwenden, haben Sie zwei Messwertgruppen. Um bei der Abfrage vollständige Ergebnisse zu erhalten, müssen Sie die Ergebnisse aus den Prometheus- und OTLP-Versionen der Messwerte manuell zusammenführen.

• Die Telemetry API fügt einem Messwertnamen keine Einheit an, wenn eine Einheit vorhanden ist, und sie fügt Zählern kein _total-Suffix 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 Datenstandort

Informationen zum Speichern Ihrer Messwertdaten 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 Erstellen von Diagrammen Ihrer Messwertdaten finden Sie unter Diagramme mit dem Metrics Explorer erstellen.

Kontingente

Informationen zu Kontingenten für die Telemetry API, siehe Limits für die Telemetry API.