Telemetry (OTLP) API overview

This document describes the Telemetry (OTLP) API, which implements the OpenTelemetry OTLP Protocol. This API is designed for use with applications that are instrumented by using one of the OpenTelemetry SDKs or that use any OpenTelemetry Collector.

OpenTelemetry is a Google Cloud-supported open source project with Google Cloud engineers staffed to ensure support for ingesting and visualizing your telemetry.

To learn more about this API, see the following reference documents:

• v1.traces overview
• v1.metrics overview
• v1.logs overview

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:

• Overview of collector-based instrumentation samples.
• OTLP metric ingestion overview.

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.

VPC Service Controls support

The Telemetry API service, whose service name is telemetry.googleapis.com, is a VPC Service Controls-supported service. Any VPC Service Controls restrictions that you create for the Telemetry API service apply only to that service. Those restrictions don't apply to any other services, including those like the cloudtrace.googleapis.com service, which can also ingest trace data.

For more information, see the following:

• VPC Service Controls documentation.
• Supported products and limitations.