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.
Best practices
When instrumenting your applications to send trace data to your Google Cloud project, we recommend that you do one of the following:
- Use an exporter that writes OTLP to a Collector, which then sends your trace data to the Telemetry API.
- Use an in-process OTLP exporter supported by an OpenTelemetry library that sends telemetry to the Telemetry API. There is no collector with this configuration.
For information about how to use the Telemetry API, see Migrate from the Cloud Trace exporter to the OTLP endpoint.
Authentication
You must configure your exporters with the credentials necessary to send trace data to your Google Cloud project. For example, to configure the exporter with your Google Cloud Application Default Credentials (ADC), add a language-specific Google Auth Library to your application. For more information and sample code, see Configure authentication.
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 Log Analytics pages. For information, see the following: