This document describes why we recommend that you send your trace data to your Google Cloud project by using the Telemetry (OTLP) API, which implements the OpenTelemetry OTLP Protocol. It also provides guidance on instrumenting your applications and where you can view your trace data. You can use the Telemetry API when you instrument your applications by using one of the OpenTelemetry SDKs or when you use a OpenTelemetry Collector.
We recommend the Telemetry API for the following reason:
The API provides compatibility with the open source OpenTelemetry ecosystem and its limits are often more generous than the limits of the Cloud Trace API, which is a proprietary Google Cloud API
Your trace data is stored in a format that is generally consistent with the proto files defined by the OpenTelemetry OTLP Protocol. Some fields might be converted from an OpenTelemetry-specific data type to a JSON data type before storage. To learn more about the storage format, see Schema for trace data.
Your instrumentation doesn't rely on a Google Cloud-specific exporter.
Some features, like Application Monitoring, rely on information that is available only when you send trace data to the Telemetry API.
OpenTelemetry is a Google Cloud-supported open source project with Google Cloud engineers staffed to ensure support for ingesting and visualizing your telemetry.
Google Cloud Observability verifies that the Cloud Trace API is enabled on your Google Cloud project before it stores any trace data. That means that if you disable the Cloud Trace API, then Google Cloud Observability discards trace data you send to the Telemetry API.
Best practices
When instrumenting your applications to send trace data to your Google Cloud project, we recommend that you use an exporter that writes OTLP-formatted data to a Collector, which then sends your trace data to the Telemetry API. In your collector, specify only the root URL:
exporters:
otlphttp:
encoding: proto
endpoint: https://telemetry.googleapis.com
OpenTelemetry detects the data type and automatically appends /v1/traces,
/v1/metrics, or /v1/logs as appropriate. For more information, see
OTLP/HTTP Request.
For examples that export trace or metric data to the Telemetry API, see the following documents:
When you can't use a collector, you can use an OpenTelemetry library that contains an in-process OTLP exporter to send telemetry to the Telemetry API. To learn how to directly export trace data, see Cloud Trace exporter to the OTLP endpoint.
Authentication
You must configure your exporters with the credentials necessary to send
data to your Google Cloud project. For example, when you use collectors, typically
you also use the googleclientauth extension to authenticate with Google
credentials.
For an example of authentication when using direct export of trace data, see Configure authentication. This example illustrates how to configure the exporter with your Google Cloud Application Default Credentials (ADC) and add a language-specific Google Auth Library to your application.
Cloud Trace and data residency
If you are using Assured Workloads because you have data-residency or Impact Level 4 (IL4) requirements, then don't use the Telemetry API to send trace spans to your project.
Where to view ingested data
You can view your trace data by using the Trace Explorer and Observability Analytics pages. For information, see the following: