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 depende de los exportadores de Google Cloud para usar los exportadores de OTLP de OpenTelemetry. Ambas configuraciones envían telemetría a tu proyecto Google Cloud . Los pasos que se indican en este documento son para la exportación en el 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 registros o métricas a tu proyecto de Google Cloud .

Por qué deberías migrar

Los SDKs de OpenTelemetry generan datos de registros, métricas y seguimientos en formato OTLP. Cuando una aplicación exporta esos datos a unGoogle Cloud proyecto con un Google Cloud exportador, este realiza los siguientes pasos:

  1. Transforma los datos registrados del formato OTLP a un formato propietario definido por 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 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 algunos campos de OTLP pueden no asignarse a un campo en el formato propietario.

Antes de comenzar

Antes de migrar tu aplicación para enviar datos de seguimiento al extremo de OTLP, habilita la API de Telemetry y asegúrate de que se te hayan otorgado los roles necesarios de Identity and Access Management (IAM). También es posible que debas otorgar roles de IAM a una cuenta de servicio.

Habilita la API de Telemetry

Asegúrate de que la API de Telemetry, la API de Cloud Logging, la API de Cloud Monitoring y la API de Cloud Trace estén habilitadas para tu proyecto. La API de Telemetry está inhabilitada de forma predeterminada.

Google Cloud console

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

Enable the APIs

Google Cloud CLI

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

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

Configura permisos

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 registros a este extremo.

Agrega dependencias

El primer paso es agregar dependencias para el exportador de seguimiento 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 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 seguimientos de Google Cloud . Los cambios requeridos son específicos para cada 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 a través de gRPC o HTTP. A continuación, debes configurar los exportadores para enviar esos registros a tu proyecto de Google Cloud .

Para configurar la autenticación, haz lo siguiente:

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

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

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

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

Java

Para autenticarte en Google Cloud Observability, 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 Google Cloud Observability, 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 Google Cloud Observability, 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 autoconfiguración del SDK de OpenTelemetry. Para ver un ejemplo completo que usa esta extensión, consulta 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(
                () -> {
                  Map<String, List<String>> gcpHeaders;
                  try {
                    credentials.refreshIfExpired();
                    gcpHeaders = credentials.getRequestMetadata();
                  } catch (IOException e) {
                    // Handle authentication error
                    throw new RuntimeException(e);
                  }
                  Map<String, String> flattenedHeaders =
                      gcpHeaders.entrySet().stream()
                          .collect(
                              Collectors.toMap(
                                  Map.Entry::getKey,
                                  entry ->
                                      entry.getValue().stream()
                                          .filter(Objects::nonNull)
                                          .filter(s -> !s.isEmpty())
                                          .collect(Collectors.joining(",")),
                                  (v1, v2) -> v2));
                  return flattenedHeaders;
                })
            .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 de OpenTelemetry y los encabezados de OTLP 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. El valor debe ser el ID de tu proyecto de Google Cloud .

Ejemplo:

export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=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 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.