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 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, bei dem Google Cloud Entwickler dafür sorgen, dass Ihre Telemetriedaten aufgenommen und visualisiert werden können.

Best Practices

Wenn Sie Ihre Anwendungen so instrumentieren, dass Tracedaten an Ihr Google Cloud Projekt gesendet werden, empfehlen wir Ihnen, einen Exporter zu verwenden, der OTLP-formatierte Daten 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 an die Telemetry API finden Sie in den folgenden Dokumenten:

• Übersicht über instrumentierungsbasierte Collector-Beispiele.
• Übersicht über die OTLP-Messwertaufnahme.

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 bei der direkten Exportierung 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:

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

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

  • Log-Autor (roles/logging.logWriter)
  • Monitoring-Messwert-Autor (roles/monitoring.metricWriter)
  • Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)

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 mit der Prometheus-Zuordnung für Google Cloud Managed Service for Prometheus geschrieben, indem 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 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 für den Fall implementiert, dass 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 den 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 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 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-Temporality werden nicht unterstützt.
HISTOGRAMM (CUMULATIVE)	CUMULATIVE	VERTEILUNG mit expliziten Buckets	/histogram
EXPONENTIAL HISTOGRAM (CUMULATIVE)	CUMULATIVE	VERTEILUNG mit exponentiellen Buckets	/histogram
HISTOGRAMM (DELTA)	DELTA	VERTEILUNG mit expliziten Buckets	/histogram:delta
EXPONENTIAL HISTOGRAM (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 die Zeichen Punkt (.) und Schrägstrich (/) mit 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. Der Unterschied in der Verarbeitung der Zeichen Punkt (.) und Schrägstrich (/) 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 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 hängt keine Einheit an einen Messwertnamen 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 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 Anzeigen und Darstellen Ihrer Messwertdaten in Diagrammen finden Sie unter Diagramme mit dem Metrics Explorer erstellen.