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 un proyecto con un Google Cloud exportador, este realiza los siguientes pasos:Google Cloud

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.

Nota: La API de Telemetry solo acepta datos de seguimiento. No puedes enviar datos de métricas ni de registros a tu proyecto de Google Cloud con este extremo.

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 facturación y la API de Telemetry

Nota: La API de Telemetry está inhabilitada de forma predeterminada.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Enable the APIs

Configura permisos

• Para obtener los permisos que necesitas para permitir que la aplicación de ejemplo envíe datos de registros, métricas y seguimientos a tu proyecto, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

  • Escritor de registros de telemetría de Cloud (roles/telemetry.tracesWriter)
  • Escritor de registros (roles/logging.logWriter)
  • Escritor de métricas de Monitoring (roles/monitoring.metricWriter)
  Nota: Si configuras tu aplicación de modo que las credenciales predeterminadas de la aplicación (ADC) dependan de una cuenta de servicio, otorga los roles de IAM anteriores a la cuenta de servicio. 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.

• Para obtener los permisos que necesitas para ver tus datos de registros, métricas y seguimientos, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

  • Visualizador de registros (roles/logging.viewer)
  • Visualizador de Monitoring (roles/monitoring.viewer)
  • Usuario de Cloud Trace (roles/cloudtrace.user)

  Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

  También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

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 que envíen 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 necesarios

Agrega a la variable de entorno OTEL_RESOURCE_ATTRIBUTES el par clave-valor que especifica tu proyecto. Para la clave, usa gcp.project_id. Para el valor, usa el ID de tu proyecto 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 ID del proyecto de cuota

El proyecto de cuota es el proyecto Google Cloud que hace un seguimiento de tu uso de las solicitudes a la API. Dado que la API de Telemetry es una API basada en el cliente, la forma en que te autentiques determinará si el proyecto de cuota se identifica automáticamente. Por ejemplo, no es necesario que especifiques el proyecto de cuota cuando usas una cuenta de servicio para la autenticación. Sin embargo, debes especificar el proyecto de cuota cuando se usan credenciales de usuario para la autenticación.

Puedes configurar un proyecto de cuota con una variable de entorno. Para determinar qué variable de entorno debes configurar para tu lenguaje de programación, consulta Configura el proyecto de cuota con una variable de entorno.

Por ejemplo, para Go, puedes establecer el proyecto de cuota de la siguiente manera:

export GOOGLE_CLOUD_QUOTA_PROJECT="QUOTA_PROJECT_ID"

Para obtener información sobre cómo resolver errores de autenticación, consulta Las credenciales de usuario no funcionan.

Nota: No actualices la variable de entorno OTEL_EXPORTER_OTLP_HEADERS con un par clave-valor que use la clave x-goog-user-project. Esta configuración puede generar valores duplicados en la solicitud, lo que provoca que fallen los comandos de la API.

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.