Telemetry API (OTLP) – Übersicht

In diesem Dokument wird die Telemetry API (OTLP) beschrieben, die das OpenTelemetry OTLP-Protokoll implementiert. Diese API ist für die Verwendung mit Anwendungen konzipiert, die mit einem der OpenTelemetry SDKs instrumentiert wurden oder einen OpenTelemetry Collector verwenden.

OpenTelemetry ist ein von Google Cloudunterstütztes Open-Source-Projekt mit Google Cloud-Entwicklern, die für die Unterstützung bei der Aufnahme und Visualisierung Ihrer Telemetriedaten sorgen.

Trace-Daten und die Telemetry API

In diesem Abschnitt finden Sie Informationen zur Telemetry API und zu Traces.

Gründe für die Verwendung der Telemetry API

Wenn Sie die Telemetry API verwenden, werden Ihre Daten in einem Format gespeichert, das im Allgemeinen mit den von OpenTelemetry OTLP Protocol definierten Proto-Dateien übereinstimmt. Felder werden jedoch möglicherweise vor dem Speichern von einem OpenTelemetry-spezifischen Datentyp in einen JSON-Datentyp konvertiert. Außerdem gelten die Limits für die Telemetry API. Diese Limits sind oft großzügiger als die für die Cloud Trace API. Schließlich basiert Ihre Instrumentierung nicht auf einem Google Cloud-spezifischen Exporttool.

Weitere Informationen zum Speicherformat finden Sie unter Schema für Tracedaten.

Wann sollte die Telemetry API verwendet werden?

Wir empfehlen, Ihre Trace-Daten mithilfe der Telemetry API an Ihr Google Cloud -Projekt zu senden. Diese API ist mit dem Open-Source-Ökosystem von OpenTelemetry kompatibel und ihre Limits sind oft großzügiger als die der Cloud Trace API, die eine proprietäreGoogle Cloud API ist. Einige Funktionen wie Application Monitoring basieren auf Informationen, die nur verfügbar sind, wenn Tracedaten an die Telemetry API gesendet werden.

Wenn Sie Ihre Anwendungen so instrumentieren, dass sie Tracedaten an IhrGoogle Cloud -Projekt senden, empfehlen wir, eine der folgenden Aktionen auszuführen:

  • Verwenden Sie einen Exporter, der OTLP in einen Collector schreibt, der Ihre Trace-Daten dann an die Telemetry API sendet.
  • Verwenden Sie einen In-Process-OTLP-Exporter, der von einer OpenTelemetry-Bibliothek unterstützt wird und Telemetrie an die Telemetry API sendet. Es gibt keinen Collector mit dieser Konfiguration.

Informationen zur Verwendung der Telemetry API finden Sie unter Vom Cloud Trace-Exporter zum OTLP-Endpunkt migrieren.

Authentifizierung

Exporter müssen autorisiert sein, Daten an Ihr Google Cloud -Projekt zu senden. Sie können den Exporter beispielsweise mit Ihren Google Cloud Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) konfigurieren, indem Sie Ihrer Anwendung eine sprachspezifische Google Auth Library hinzufügen. Weitere Informationen und Beispielcode finden Sie unter Authentifizierung konfigurieren.

Cloud Trace und Datenstandort

Wenn Sie Assured Workloads verwenden, weil Sie Anforderungen an den Datenstandort oder Impact Level 4 (IL4) haben, sollten Sie die Telemetry API nicht zum Senden von Trace-Spans verwenden.

Messwertdaten und die Telemetry API

In diesem Abschnitt wird beschrieben, wie Cloud Monitoring Messwerte verarbeitet, die mit dem otlphttp-Exporter und einem OpenTelemetry Collector oder von Anwendungen erfasst werden, die mit einem der OpenTelemetry SDKs instrumentiert sind.

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 die 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 in der Reihenfolge ihrer Priorität aufgeführt:

prometheus-target-Label Verwendeter Wert (in Prioritätsreihenfolge)
location (erforderlich)
  • Attribut location
  • Attribut cloud.availability_zone
  • Attribut cloud.region
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, falls 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
Punkt ablehnen, wenn leer
  • 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

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 ein target_info-Messwert 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.
    • An 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 Messgerät-Zeitachse 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-Unbekannte 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  
HISTOGRAMM (KUMULATIV) CUMULATIVE VERTEILUNG mit expliziten Buckets /histogram  
EXPONENTIAL HISTOGRAM (CUMULATIVE) 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 Zeichen Punkt (.) und Schrägstrich (/) in Messwertnamen. Beim googlemanagedprometheus-Export werden alle Instanzen dieser Zeichen in Unterstriche (_) 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 Aufnahmepfade unterscheiden sich die resultierenden Messwertdeskriptoren zwischen Messwerten, die mit dem googlemanagedprometheus-Exporter aufgenommen werden, und Messwerten, die mit dem otlphttp-Exporter aufgenommen 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.

  • Die Telemetry API hängt keine Einheit an einen Messwertnamen an, wenn eine Einheit vorhanden ist, und kein _total-Suffix an Zähler. 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 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.

  • In der API werden die Labels scope_version oder scope_name nicht festgelegt, wenn sie leere Werte haben.

Wo Sie aufgenommene Daten ansehen können

Trace-Daten, die über die Telemetry API aufgenommen werden, können auf der Seite Trace Explorer aufgerufen werden. Informationen zum Aufrufen Ihrer Trace-Daten finden Sie in den folgenden Artikeln:

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.

Unterstützung durch VPC Service Controls

Der Telemetry API-Dienst mit dem Dienstnamen telemetry.googleapis.com ist ein von VPC Service Controls unterstützter Dienst. Alle VPC Service Controls-Einschränkungen, die Sie für den Telemetry API-Dienst erstellen, gelten nur für diesen Dienst. Diese Einschränkungen gelten nicht für andere Dienste, einschließlich Dienste wie cloudtrace.googleapis.com, in die auch Tracedaten aufgenommen werden können.

Hier finden Sie weitere Informationen: