v1.traces-Übersicht

In diesem Dokument wird beschrieben, warum wir empfehlen, Ihre Trace-Daten mit der Google Cloud Telemetry (OTLP) API an Ihr Projekt zu senden, die das OpenTelemetry Protocol implementiert. Außerdem finden Sie hier eine Anleitung zum Instrumentieren Ihrer Anwendungen und Informationen dazu, wo Sie Ihre Trace-Daten ansehen können. Sie können die Telemetry API verwenden, wenn Sie Ihre Anwendungen mit einem der OpenTelemetry SDKs instrumentieren oder einen OpenTelemetry Collector verwenden.

Wir empfehlen die Telemetry API aus folgenden Gründen:

  • Die API ist mit dem Open-Source-Ökosystem OpenTelemetry kompatibel und ihre Limits sind oft großzügiger als die der Cloud Trace API, einer proprietären Google Cloud API.

  • Ihre Trace-Daten werden in einem Format gespeichert, das im Allgemeinen mit den Protobuf-Dateien übereinstimmt, die vom OpenTelemetry Protocol definiert werden. Einige Felder werden möglicherweise vor der Speicherung von einem OpenTelemetry-spezifischen Datentyp in einen JSON-Datentyp konvertiert. Weitere Informationen zum Speicherformat finden Sie unter Schema für Trace-Daten.

  • Ihre Instrumentierung ist nicht von einem Google Cloudbestimmten Exporter abhängig.

  • Einige Funktionen wie Application Monitoring basieren auf Informationen, die nur verfügbar sind, wenn Sie Trace-Daten an die Telemetry API senden.

OpenTelemetry ist ein Google Cloud-unterstütztes Open-Source-Projekt, bei dem Google Cloud Entwickler dafür sorgen, dass die Aufnahme und Visualisierung Ihrer Telemetriedaten unterstützt wird.

Google Cloud Observability prüft, ob die Cloud Trace API in Ihrem Projekt aktiviert ist , bevor Trace-Daten gespeichert werden Google Cloud . Wenn Sie die Cloud Trace API deaktivieren, verwirft Google Cloud Observability Trace-Daten, die Sie an die Telemetry API senden.

Best Practices

Wenn Sie Ihre Anwendungen so instrumentieren, dass Trace-Daten an Ihr Google Cloud Projekt gesendet werden, empfehlen wir, einen Exporter zu verwenden, der Daten im OTLP-Format in einen Collectorschreibt. Dieser sendet dann Ihre Trace-Daten 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 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:

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 Trace-Daten 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 die Erweiterung googleclientauth, um sich mit Google-Anmeldedaten zu authentifizieren.

Ein Beispiel für die Authentifizierung bei der direkten Exportierung von Trace-Daten 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 dem Dienstkonto, das von der Anwendung verwendet wird, die folgenden IAM-Rollen (Identity and Access Management) zu:

Cloud Trace und Datenstandort

Wenn Sie Assured Workloads verwenden, weil Sie Anforderungen an den Datenstandort oder Impact Level 4 (IL4) haben, verwenden Sie die Telemetry API nicht, um Trace-Spans an Ihr Projekt zu senden.

Aufgenommene Daten ansehen

Sie können Ihre Trace-Daten auf den Seiten Trace-Explorer und Observability Analytics ansehen. Weitere Informationen finden Sie unter:

Kontingente

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