Migra del exportador de seguimiento al extremo de OTLP

En este documento, se describe cómo migrar una aplicación instrumentada con OpenTelemetry y que se basa en exportadores de Google Cloud para usar los exportadores de OTLP de OpenTelemetry. Ambas configuraciones envían telemetría a tu proyecto de Google Cloud. Los pasos de este documento son para la exportación en proceso que realiza el SDK de OpenTelemetry.

En este documento, se describe cómo exportar datos de seguimiento cuando usas la instrumentación manual. Esta guía, que se proporciona para Java, Go y Python, no se aplica al envío de datos de registro o métricas a tu proyecto de Google Cloud.

Por qué deberías migrar

Los SDK de OpenTelemetry generan datos de registro, métrica y seguimiento en el formato OTLP. Cuando una aplicación exporta esos datos a un proyecto de Google Cloud con un exportador de Google Cloud , ese exportador realiza los siguientes pasos:

  1. Transforma los datos registrados del formato OTLP en un formato propietario que define la API de Cloud Logging, la API de Cloud Monitoring o la API de Cloud Trace.
  2. Envía los datos transformados a la API adecuada, que luego se almacena en tu proyecto de Google Cloud.

Para los datos de seguimiento, te recomendamos que migres tu aplicación para usar la API de Telemetry (OTLP) para exportar datos, ya que esta exportación no requiere una transformación de datos. La transformación de datos puede provocar la pérdida de algunos datos. Por ejemplo, el formato propietario puede tener límites más bajos para ciertos campos, o bien algunos campos de la OTLP pueden no asignarse a un campo en el formato propietario.

Guía de migración para la instrumentación manual

En esta sección, se describe cómo modificar tu aplicación para que envíe tus datos de seguimiento a tu proyecto de Google Cloud con la API de Telemetry. No puedes enviar datos de métricas ni de registro a este extremo.

Agrega dependencias

El primer paso es agregar dependencias para el exportador de seguimientos de OTLP de OpenTelemetry en tu aplicación. Selecciona las versiones de dependencia adecuadas para tu aplicación y sistema de compilación.

Java

Para una aplicación de Java que usa el sistema de compilación de Gradle, haz lo siguiente:

// build.gradle
implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.47.0")

Go

Para una aplicación de Golang, asegúrate de que el archivo go.mod tenga las siguientes dependencias:

// go.mod file
require(
  // OTLP exporter that uses grpc protocol for export
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.34.0
  // Alternatively, for export using http/protobuf protocol, use:
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.34.0
)

Python

Para una aplicación de Python, instala las siguientes dependencias o actualiza el archivo requirements.txt:

# Requirements.txt - use appropriate versions
#
# OTLP exporter that uses grcp protocol for export
opentelemetry-exporter-otlp-proto-grpc==1.30.0
grpcio==1.70.0
# Alternatively, for export using http/protobuf protocol, use:
opentelemetry-exporter-otlp-proto-http==1.30.0

Reemplaza el uso de exportadores de Google Cloud por exportadores de OTLP

Actualiza el código de tu aplicación para que el SDK de OpenTelemetry esté configurado para usar los exportadores de OTLP de OpenTelemetry en lugar del exportador de seguimiento de Google Cloud . Los cambios obligatorios son específicos del idioma.

Java

import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.sdk.trace.export.SpanExporter;
import io.opentelemetry.sdk.trace.samplers.Sampler;

// Initialize OpenTelemetry SDK with OTLP exporters
public static OpenTelemetry initOpenTelemetry() {
    // Initialize the OTLP gRPC exporter
    SpanExporter otlpGrpcSpanExporter =
        OtlpGrpcSpanExporter.builder()
            .setTimeout(2, TimeUnit.SECONDS)
            .build();

    // Initialize OpenTelemetry tracer provider
    SdkTracerProvider tracerProvider = SdkTracerProvider.builder()
        .setResource(resource)
        .setSampler(Sampler.traceIdRatioBased(0.02))
        .addSpanProcessor(
            BatchSpanProcessor.builder(otlpGrpcSpanExporter)
                .setScheduleDelay(100, TimeUnit.MILLISECONDS)
                .build());

    // Configure OpenTelemetry SDK instacne to use the tracer provider
    // configured with OTLP exporter
    OpenTelemetrySdk openTelemetrySdk =
        OpenTelemetrySdk.builder()
            .setTracerProvider(tracerProvider)
            .build();
}

Go

import (
    "context"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    // other dependencies
)

// Initializes OpenTelemetry with OTLP exporters
func init() {
    ctx := context.Background()

    // Initialize the OTLP gRPC exporter
    exporter, err := otlptracegrpc.New(ctx)
    if err != nil {
        panic(err)
    }
    // initialize OpenTelemetry tracer provdier
    tp := sdktrace.NewTracerProvider(
        sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.02)),
        sdktrace.WithBatcher(exporter)
    )

    // configure OpenTelemetry SDK instance to use the tracer provider
    // configured with OTLP exporter
    otel.SetTracerProvider(tp)
}

Python

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
    OTLPSpanExporter,
)
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

# Initialize OpenTelemetry with OTLP exporters
def init():
    # Initialize the OTLP gRPC or http exporter
    otlp_grpc_exporter = OTLPSpanExporter()

    # Initialize OpenTelemetry TracerProvider
    trace_provider = TracerProvider(resource=resource).add_span_processor(
    BatchSpanProcessor(otlp_grpc_exporter)
    )

    # Configure OpenTelemetry tracing API with the initialized tracer provider
    trace.set_tracer_provider(trace_provider)

Configura la autenticación

Con los cambios anteriores en la configuración del SDK de OpenTelemetry, tu aplicación está configurada para exportar seguimientos con los exportadores de OTLP de OpenTelemetry mediante gRPC o HTTP. A continuación, debes configurar las exportaciones para que envíen esos seguimientos a tu proyecto de Google Cloud.

Para configurar la autenticación, haz lo siguiente:

  1. Configura encabezados de autenticación para las llamadas de exportación.
  2. Configura los atributos de recursos y los encabezados de OTLP de OpenTelemetry.
  3. Configura el extremo del exportador.

En esta sección, se detalla cada uno de estos pasos.

Configura los encabezados de autenticación para las llamadas de exportación

Para configurar el exportador con tus credenciales predeterminadas de la aplicación (ADC) de Google Cloud, agrega una biblioteca de Google Auth específica del lenguaje.

Java

Para autenticarte en la Observabilidad de Google Cloud, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

// build.gradle
// Google Auth Library
implementation("com.google.auth:google-auth-library-oauth2-http:1.32.1")

Go

Para autenticarte en la Observabilidad de Google Cloud, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

// go.mod file
require (
    // When using gRPC based OTLP exporter, auth is built-in
    google.golang.org/grpc v1.70.0
    // When using http based OTLP exported, use explicit auth library
    golang.org/x/oauth2 v0.26.0
)

Python

Para autenticarte en la Observabilidad de Google Cloud, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

# requirements.txt
# Google Auth Library
google-auth==2.38.0

A continuación, actualiza el código de la aplicación que construye el exportador de intervalos de OTLP para que agregue los tokens de autorización recuperados de la biblioteca a los encabezados. Este paso es específico del lenguaje, pero la implementación es similar para todos los lenguajes.

Java

Te recomendamos que uses la extensión de autenticación de Google Cloud cuando uses el módulo de configuración automática del SDK de OpenTelemetry. Para ver un ejemplo completo que usa esta extensión, consulta el ejemplo de seguimiento de OTLP con autenticación de Google.

import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.sdk.trace.export.SpanExporter;
import io.opentelemetry.sdk.trace.samplers.Sampler;

import com.google.auth.oauth2.GoogleCredentials;

// Initialize OpenTelemetry SDK with OTLP exporters
public static OpenTelemetry initOpenTelemetry() {
    // Retrieve and store application-default credentials
    GoogleCredentials credentials;
    try {
       credentials = GoogleCredentials.getApplicationDefault();
    } catch (IOException e) {
      // Handle authentication error
      throw new RuntimeException(e);
    }

   // Update gRPC span exporter to add the authorization headers
   // If you are using the Autoconfigure module, we recommend using
   // Google Cloud Authentication Extension.
   // See https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/gcp-auth-extension
   SpanExporter otlpGrpcSpanExporter =
        OtlpGrpcSpanExporter.builder()
            .setHeaders(() -> {
                try {
                    credentials.refreshIfExpired();
                } catch (IOException e) {
                    // Handle authentication error
                    throw new RuntimeException(e);
                }
                return Map.of("Authorization", "Bearer " + credentials.getAccessToken().getTokenValue());
            })
            .setTimeout(2, TimeUnit.SECONDS)
            .build();

  // Other OpenTelemetry configuration remains unaffected
}

Go

import (
    "context"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/oauth"
)

// Initializes OpenTelemetry with OTLP exporters
func init() {
    ctx := context.Background()

    // Retrieve and store Google application-default credentials
    creds, err := oauth.NewApplicationDefault(ctx)
    if err != nil {
        panic(err)
    }

    // Update the previously created OTLP gRPC span exporter to
    // add authorization headers
    exporter, err := otlptracegrpc.New(
        ctx,
        otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds))
    )

    // Other OpenTelemetry configuration remains unaffected.
}

Python

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
    OTLPSpanExporter,
)
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

import google.auth
import google.auth.transport.grpc
import google.auth.transport.requests
import grpc
from google.auth.transport.grpc import AuthMetadataPlugin

# Initialize OpenTelemetry with OTLP exporters
def init():
    # Retrieve and store Google application-default credentials
    credentials, project_id = google.auth.default()
    # Request used to refresh credentials upon expiry
    request = google.auth.transport.requests.Request()

    # Supply the request and credentials to AuthMetadataPlugin
    # AuthMeatadataPlugin inserts credentials into each request
    auth_metadata_plugin = AuthMetadataPlugin(
        credentials=credentials, request=request
    )

    # Initialize gRPC channel credentials using the AuthMetadataPlugin
    channel_creds = grpc.composite_channel_credentials(
        grpc.ssl_channel_credentials(),
        grpc.metadata_call_credentials(auth_metadata_plugin),
    )

    # Update the previously created OTLP gRPC span exporter to add authorization
    # credentials
    otlp_grpc_exporter = OTLPSpanExporter(credentials=channel_creds)

    # Other OpenTelementry configuration remains unaffected

Configura los atributos de recursos y los encabezados de OTLP de OpenTelemetry necesarios

Configura las siguientes variables de entorno de OpenTelemetry:

  • OTEL_RESOURCE_ATTRIBUTES: Configura esta variable de entorno para establecer la clave gcp.project_id en los atributos de recursos de OpenTelemetry. Establece el valor como el ID de tu proyecto de Google Cloud.

  • OTEL_EXPORTER_OTLP_HEADERS: Configura esta variable de entorno para agregar el encabezado x-goog-user-project. El valor debe ser el ID de tu proyecto de Google Cloud desde el que se consumirá la cuota del servicio. Por lo general, el valor se establece en el mismo valor que para la clave gcp.project_id.

Ejemplo:

export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=PROJECT_ID"
export OTEL_EXPORTER_OTLP_HEADERS="x-goog-user-project=QUOTA_PROJECT_ID"

Para obtener más información sobre las variables de entorno de OpenTelemetry, consulta Configuración general del SDK.

Configura el extremo del exportador

Establece el valor de la variable de entorno OTEL_EXPORTER_OTLP_ENDPOINT en el extremo de la OTLP para Google Cloud.

Ejemplo:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://telemetry.googleapis.com

Para obtener más información sobre las variables de entorno de OpenTelemetry, consulta Configuración general del SDK.

Permisos necesarios

Existen roles y permisos de administración de identidades y accesos (IAM) que te otorgan a ti o a una cuenta de servicio la capacidad de escribir datos de seguimiento en la API de Telemetry y almacenarlos en tu proyecto de Google Cloud. Por ejemplo, si solo se te otorgaron roles o permisos de Cloud Trace, esos permisos no te permitirán escribir datos con la API de Telemetry.

Para obtener más información, consulta Cómo funcionan las credenciales predeterminadas de la aplicación y Configura las credenciales predeterminadas de la aplicación (ADC) para un entorno de desarrollo local.

APIs requeridas

La API de Telemetry está inhabilitada de forma predeterminada. Debes habilitar esta API. A continuación, se proporciona información sobre las APIs necesarias para enviar datos de telemetría a un proyecto de Google Cloud y para ver estos datos:

Consola de Google Cloud

Enable the Telemetry API, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

Google Cloud CLI

Enable the Telemetry API, Cloud Logging, and Cloud Monitoring, and Cloud Trace APIs: 

gcloud services enable telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com