This document describes how to configure the in-process export of trace data by the OpenTelemetry SDK to your Google Cloud project. The examples for Java, Go, Python, and Node.js show how to configure the SDK to send trace data to the Telemetry (OTLP) API when you use manual instrumentation. For each language, the page provides information for using OTLP exporters to send trace data using the supported export protocols.
The instrumentation described on this page applies only to trace data. It doesn't send log or metric data to your Google Cloud project.
If your application relies on an OpenTelemetry collector to send trace data to your Google Cloud project, then this document doesn't apply:
- For instrumentation samples, see Collector-based instrumentation samples.
- For information about collectors, see Google-Built OpenTelemetry Collector.
Why you should migrate
The OpenTelemetry SDKs generate log, metric, and trace data in in a format that is generally consistent with the proto files defined by the OpenTelemetry Protocol. However, fields might be converted from an OpenTelemetry-specific data type to a JSON data type before storage.
When an application exports that data to a Google Cloud project by using a Google Cloud exporter, that exporter performs the following steps:
- Transforms the recorded data from OTLP-format into a proprietary format defined by the Cloud Logging API, the Cloud Monitoring API, or the Cloud Trace API.
- Sends the transformed data to the appropriate API, which is then stored in your Google Cloud project.
For trace data, we recommend that you migrate your application to use the Telemetry (OTLP) API to export data, because this export doesn't require a data transformation. Data transformation might cause loss of some data. For example, the proprietary format might have lower limits for certain fields, or some OTLP fields might not map to a field in the proprietary format.
Available samples
The sample applications referenced on this page are available in GitHub. Most applications are configured to export trace data by using gRPC, which means that they use protobuf-encoded data using gRPC wire format over HTTP/2 connections. Example code is also provided for applications that are configured to export trace data as protobuf-encoded data over HTTP connections:
-
The sample application is configured to export traces as protobuf-encoded data over HTTP connections. If you prefer to use gRPC, then the instrumentation in this sample is applicable. However, you need to modify the system properties that the autoconfiguration module consumes. The sample application specifies the
http/protobufexporter. To use gRPC, change this setting togrpc.We recommend that your Java applications, like the sample application, use the OpenTelemetry SDK Autoconfigure module to configure the SDK.
Go application that uses gRPC and Go application that uses HTTP
There are two Go repositories. In one repository, the sample application uses gRPC. The sample in the other repository uses protobuf-encoded data over HTTP connections.
-
This repository contains two samples, one for gRPC and one that uses protobuf-encoded data over HTTP connections.
-
This repository contains two samples, one for gRPC and one that uses protobuf-encoded data over HTTP connections.
Before you begin
Before you migrate your application to send trace data to the OTLP endpoint, enable the Telemetry API and make sure that you have been granted the required Identity and Access Management (IAM) roles. You might also need to grant IAM roles to a service account.
Enable billing and the Telemetry API
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.