Migrar del exportador de trazas al endpoint OTLP

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

En este documento se describe cómo exportar datos de traza cuando se usa la instrumentación manual. Estas directrices, que se proporcionan para Java, Go y Python, no se aplican al envío de datos de registro o de métricas a tu Google Cloud proyecto.

Por qué deberías migrar

Los SDKs de OpenTelemetry generan datos de registro, métricas y trazas en formato OTLP. Cuando una aplicación exporta esos datos a un proyecto mediante un exportador, este realiza los siguientes pasos:Google Cloud 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 correspondiente, que se almacenan en tu Google Cloud proyecto.

En el caso de los datos de traza, te recomendamos que migres tu aplicación para usar la API 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 inferiores para determinados campos o puede que algunos campos de OTLP no se correspondan con ningún campo del formato propietario.

Nota: La API Telemetry solo acepta datos de trazas. No puedes enviar datos de métricas ni de registro a tu proyecto de Google Cloud

mediante este endpoint.

Antes de empezar

Antes de migrar tu aplicación para enviar datos de traza al endpoint de OTLP, habilita la API Telemetry y asegúrate de que se te han concedido los roles de Gestión de Identidades y Accesos (IAM) necesarios. También puede que tengas que conceder roles de gestión de identidades y accesos a una cuenta de servicio.

Habilitar la facturación y la API Telemetry

Nota: La API 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.

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Configurar permisos

• Para obtener los permisos que necesitas para que la aplicación de ejemplo envíe datos de registro, métricas y trazas a tu proyecto, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en tu proyecto:

  • Escritor de trazas de telemetría de Cloud (roles/telemetry.tracesWriter)
  • Escritor de registros (roles/logging.logWriter)
  • Editor de las métricas de monitorización (roles/monitoring.metricWriter)
  Nota: Si configuras tu aplicación de forma que las credenciales predeterminadas de la aplicación (ADC) dependan de una cuenta de servicio, concede 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 Configurar las credenciales predeterminadas de la aplicación (ADC) en un entorno de desarrollo local.

• Para obtener los permisos que necesitas para ver tus datos de registro, métricas y trazas, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en tu proyecto:

  • Visualizador de registros (roles/logging.viewer)
  • Lector de monitorización (roles/monitoring.viewer)
  • Usuario de Cloud Trace (roles/cloudtrace.user)

  Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

  También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

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 los datos de la traza a tu proyecto de Google Cloud mediante la API Telemetry. No puedes enviar datos de métricas ni de registros a este endpoint.

Añadir dependencias

El primer paso es añadir dependencias para el exportador de seguimiento OTLP de OpenTelemetry en tu aplicación. Selecciona las versiones de las dependencias adecuadas para tu aplicación y tu sistema de compilación.

Java

En el caso de una aplicación Java que utilice el sistema de compilación Gradle, sigue estos pasos:

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

Go

En el caso de 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

En el caso de 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

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

Actualice el código de su aplicación para que el SDK de OpenTelemetry se configure de forma que utilice los exportadores OTLP de OpenTelemetry en lugar del exportador de seguimiento Google Cloud . Los cambios necesarios dependen 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)

Configurar la autenticación

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

Para configurar la autenticación, haz lo siguiente:

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

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

Configurar los encabezados de autenticación de las llamadas de exportación

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

Java

Para autenticarte en Trace, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en 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 Trace, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en 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 Trace, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en 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 crea el exportador de intervalos de OTLP para que añada los tokens de autorización obtenidos de la biblioteca a los encabezados. Este paso es específico de cada idioma, pero la implementación es similar en todos los idiomas.

Java

Te recomendamos que uses la extensión de autenticación de Google Cloud cuando utilices el módulo de configuración automática del SDK de OpenTelemetry. Para ver un ejemplo completo que utilice esta extensión, consulta OTLP Trace with Google Auth Example (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

Configurar los atributos de recursos de OpenTelemetry necesarios

Añade a la variable de entorno OTEL_RESOURCE_ATTRIBUTES el par clave-valor que especifica tu proyecto. Para la clave, usa gcp.project_id. En el valor, usa 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.

Definir el ID de proyecto de cuota

El proyecto de cuota es el proyecto que registra el uso que haces de las solicitudes a la API. Google Cloud Como la API 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 usen credenciales de usuario para la autenticación.

Puedes definir un proyecto de cuota mediante una variable de entorno. Para determinar qué variable de entorno debes definir para tu lenguaje de programación, consulta Definir el proyecto de cuota mediante una variable de entorno.

Por ejemplo, en Go, puedes definir 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 el artículo Las credenciales de usuario no funcionan.

Nota: No actualice 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 provocar que se dupliquen los valores en la solicitud, lo que hace que fallen los comandos de la API.

Configurar el endpoint del exportador

Define el valor de la variable de entorno OTEL_EXPORTER_OTLP_ENDPOINT en el endpoint de OTLP de 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.