Migrar del exportador de trazas al endpoint OTLP

En este documento se describe cómo configurar la exportación en proceso de datos de traza mediante el SDK de OpenTelemetry a tu proyecto de Google Cloud . En los ejemplos de Java, Go, Python y Node.js se muestra cómo configurar el SDK para enviar datos de trazas a la API Telemetry (OTLP) cuando se usa la instrumentación manual. En cada idioma, la página proporciona información sobre cómo usar los exportadores de OTLP para enviar datos de trazas mediante los protocolos de exportación admitidos.

La instrumentación descrita en esta página solo se aplica a los datos de traza. No envía datos de registro ni de métricas a tu proyecto Google Cloud .

Si tu aplicación utiliza un recolector de OpenTelemetry para enviar datos de traza a tu proyecto de Google Cloud , este documento no es aplicable:

Por qué deberías migrar

Los SDKs de OpenTelemetry generan datos de registro, métricas y trazas en un formato que suele ser coherente con los archivos proto definidos por el protocolo OTLP de OpenTelemetry. Sin embargo, los campos se pueden convertir de un tipo de datos específico de OpenTelemetry a un tipo de datos JSON antes de almacenarse.

Cuando una aplicación exporta esos datos a un Google Cloud proyecto mediante 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 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.

mediante este endpoint.

Muestras disponibles

Las aplicaciones de ejemplo a las que se hace referencia en esta página están disponibles en GitHub. La mayoría de las aplicaciones están configuradas para exportar datos de traza mediante gRPC, lo que significa que usan datos codificados con protobuf mediante el formato de cable gRPC a través de conexiones HTTP/2. También se proporciona código de ejemplo para las aplicaciones que están configuradas para exportar datos de traza como datos codificados con protobuf a través de conexiones HTTP:

  • Aplicación Java

    La aplicación de ejemplo está configurada para exportar trazas como datos codificados con protobuf a través de conexiones HTTP. Si prefieres usar gRPC, puedes usar la instrumentación de este ejemplo. Sin embargo, debe modificar las propiedades del sistema que consume el módulo de autoconfiguración. La aplicación de ejemplo especifica el exportador http/protobuf. Para usar gRPC, cambia este ajuste a grpc.

    Te recomendamos que tus aplicaciones Java, como la aplicación de ejemplo, usen el módulo de configuración automática del SDK de OpenTelemetry para configurar el SDK.

  • Aplicación Go que usa gRPC y aplicación Go que usa HTTP

    Hay dos repositorios de Go. En un repositorio, la aplicación de ejemplo usa gRPC. La muestra del otro repositorio usa datos codificados con protobuf a través de conexiones HTTP.

  • Aplicación de Python

    Este repositorio contiene dos ejemplos: uno para gRPC y otro que usa datos codificados con protobuf a través de conexiones HTTP.

  • Aplicación Node.js

    Este repositorio contiene dos ejemplos: uno para gRPC y otro que usa datos codificados con protobuf a través de conexiones HTTP.

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 hayan 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

  1. 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.

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

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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

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

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. 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

    8.

    Configurar 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 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, añade las siguientes dependencias al script build.gradle:

    // use the latest versions
implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.56.0")
implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:1.56.0")

    Go

    En esta sección se muestran los cambios que debes hacer en tus dependencias al usar gRPC para la exportación. Si usas datos codificados con protobuf en conexiones HTTP para la exportación, incluye el paquete otlptracehttp como dependencia. Para obtener más información, consulta Aplicación Go que usa HTTP.

    En el caso de una aplicación Go que utilice gRPC para la exportación, actualiza el archivo go.mod para incluir la siguiente dependencia:

    // go.mod file
require(
  // OTLP exporter that uses grpc protocol for export
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.38.0
)

    Python

    En esta sección se muestran los cambios que debes hacer en tus dependencias al usar gRPC para la exportación. Si usas datos codificados con protobuf en conexiones HTTP para la exportación, incluye el paquete opentelemetry-exporter-otlp-proto-http como requisito. Para obtener más información, consulta Aplicación Python.

    En el caso de una aplicación de Python que use gRPC para la exportación, 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.39.0
grpcio==1.76.0

    Node.js

    En esta sección se muestran los cambios que debes hacer en tus dependencias al usar gRPC para la exportación. Si usas datos codificados con protobuf en conexiones HTTP para la exportación, incluye el paquete @opentelemetry/exporter-trace-otlp-proto como dependencia. Para obtener más información, consulta Aplicación Node.js.

    En el caso de una aplicación Node.js que use gRPC, añade las siguientes dependencias.

    "@opentelemetry/exporter-trace-otlp-grpc": "0.203.0",
"@grpc/grpc-js": "1.13.4",

    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

    En el caso de una aplicación Java, haz lo siguiente:

    1. Añade las siguientes instrucciones de importación:

      import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;

    2. Actualiza el código de la aplicación para usar el módulo de configuración automática del SDK de OpenTelemetry para configurar el SDK:

      public static void main(String[] args) {
    // Configure the OpenTelemetry pipeline with Auto configuration
    openTelemetrySdk = AutoConfiguredOpenTelemetrySdk.initialize().getOpenTelemetrySdk();
    ...
}

    3. Configura las propiedades del sistema que consume el módulo de configuración automática en el tiempo de ejecución. Ese módulo usa esas propiedades para inicializar el SDK. También puedes usar variables de entorno en lugar de propiedades del sistema. Para obtener más información, consulta Variables de entorno y propiedades del sistema.

      La aplicación de ejemplo define las propiedades del sistema en la secuencia de comandos build.gradle:

      // You can switch the desired protocol here by changing `otel.exporter.otlp.protocol`.
def autoconf_config = [
  '-Dotel.exporter.otlp.endpoint=https://telemetry.googleapis.com',
  '-Dotel.traces.exporter=otlp',
  '-Dotel.logs.exporter=none',
  '-Dotel.metrics.exporter=none',
  '-Dotel.service.name=my-service',
  '-Dotel.exporter.otlp.protocol=http/protobuf',
  '-Dotel.java.global-autoconfigure.enabled=true',
  // ID of your Google Cloud Project, required by the auth extension
  '-Dgoogle.cloud.project=PROJECT_ID',
]

// Now pass the config as JVM arguments to your java application:
application {
        // Replace with the fully qualified name of your Main class.
  mainClassName = 'com.example.Main'
  applicationDefaultJvmArgs = autoconf_config
}

      Si prefieres exportar datos de seguimiento mediante gRPC, define el protocolo OTLP como grpc en lugar de http/protobuf.

    Go

    En esta sección se muestran los cambios que debes hacer al usar gRPC para la exportación. Si usas datos codificados con protobuf en conexiones HTTP para la exportación, debes importar el paquete otlptracehttp y configurar el exportador con las opciones correspondientes. Para obtener más información, consulta Aplicación Go que usa HTTP.

    En el caso de una aplicación Go que use gRPC para la exportación, añade las siguientes instrucciones de importación:

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

    Además, actualiza el código de inicialización para configurar TraceProvider con el exportador gRPC:

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

// creds: configure Application Default Credentials

// Initialize the OTLP gRPC exporter
exporter, err := otlptracegrpc.New(ctx)
if err != nil {
  panic(err)
}

// set OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=<project_id>"
// set endpoint with OTEL_EXPORTER_OTLP_ENDPOINT=https://<endpoint>
// set OTEL_EXPORTER_OTLP_HEADERS="x-goog-user-project=<project_id>"
exporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds)))
if err != nil {
  panic(err)
}

tp := sdktrace.NewTracerProvider(
  // For this example code we use sdktrace.AlwaysSample sampler to sample all traces.
  // In a production application, use sdktrace.TraceIDRatioBased with a desired probability.
  sdktrace.WithSampler(sdktrace.AlwaysSample()),
  sdktrace.WithBatcher(exporter))

otel.SetTracerProvider(tp)

    Python

    En esta sección se muestran los cambios que debes hacer al usar gRPC para la exportación. Si usas datos codificados con protobuf en conexiones HTTP para la exportación, debes importar desde el paquete opentelemetry.exporter.otlp.proto.http y configurar el exportador con las opciones correspondientes. Para obtener más información, consulta Aplicación Python.

    En una aplicación Python que use gRPC para la exportación, añade las siguientes importaciones:

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

    Además, actualiza el código de inicialización para configurar TraceProvider con el exportador gRPC:

    # Initialize OpenTelemetry with OTLP exporters

# channel_creds: configure Application Default Credentials

trace_provider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(
    OTLPSpanExporter(
        credentials=channel_creds,
        endpoint="https://telemetry.googleapis.com:443/v1/traces",
    )
)
trace_provider.add_span_processor(processor)
trace.set_tracer_provider(trace_provider)
tracer = trace.get_tracer("my.tracer.name")

    Node.js

    En esta sección se muestran los cambios que debes hacer al usar gRPC para la exportación. Si usas datos codificados con protobuf a través de conexiones HTTP para la exportación, importa el paquete @opentelemetry/exporter-trace-otlp-proto. Para obtener más información, consulta Aplicación Node.js.

    En una aplicación Node.js que use gRPC para la exportación, añade las siguientes importaciones:

    import {OTLPTraceExporter} from '@opentelemetry/exporter-trace-otlp-grpc';

    Además, actualiza el código de inicialización para configurar TraceProvider con el exportador gRPC:

    
// Express App that exports traces via gRPC with protobuf
async function main() {
  // authenticatedClient: configure Application Default Credentials

  // Configure the TraceExporter
  const sdk = new NodeSDK({
    traceExporter: new OTLPTraceExporter({
      credentials: credentials.combineChannelCredentials(
        credentials.createSsl(),
        credentials.createFromGoogleCredential(authenticatedClient),
      ),
    }),
  });
  sdk.start();
}

    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 Google Cloud Observability, 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.

    En el caso de una aplicación Java que use el módulo de configuración automática del SDK de OpenTelemetry, te recomendamos que también uses la extensión de autenticación de Google Cloud.

    // build.gradle
implementation("io.opentelemetry.contrib:opentelemetry-gcp-auth-extension:1.52.0-alpha")

    Go

    Para autenticarte en Google Cloud Observability, 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.

    En el caso de una aplicación Go que utilice gRPC para la exportación, actualiza el archivo go.mod para incluir la siguiente dependencia:

    // go.mod file
require (
    // When using gRPC based OTLP exporter, auth is built-in
    google.golang.org/grpc v1.75.1
)

    En el caso de una aplicación Go que utilice HTTP para la exportación, actualiza el archivo go.mod para incluir la siguiente dependencia:

    // go.mod file
require (
    // When using http based OTLP exported, use explicit auth library
  golang.org/x/oauth2 v0.31.0
)

    Python

    Para autenticarte en Google Cloud Observability, 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.

    En el caso de una aplicación de Python, añade las siguientes importaciones:

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

    Node.js

    Para autenticarte en Google Cloud Observability, 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.

    En el caso de una aplicación Node.js, añade las siguientes dependencias:

    "google-auth-library": "9.15.1",

    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

    Si tienes una aplicación Java que usa el módulo de configuración automática del SDK de OpenTelemetry y la extensión de autenticación de Google Cloud, no tienes que seguir ningún paso especial durante la inicialización de la aplicación. El módulo de configuración automática realiza automáticamente los pasos necesarios para configurar el ADC.

    Go

    En esta sección se muestran los cambios que debes hacer al usar gRPC para la exportación. Si usas datos codificados con protobuf a través de conexiones HTTP para la exportación, debes importar el paquete otlptracehttp y configurar el exportador para que sea un objeto otlptracehttp. Para obtener más información, consulta Aplicación Go que usa HTTP.

    En el caso de una aplicación Go que usa gRPC para la exportación, añade las siguientes declaraciones de importación:

    import (
    "context"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    // other dependencies
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/oauth"
)

    Además, actualiza el código de inicialización para configurar ADC antes de crear una instancia del exportador de gRPC:

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

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

// set OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=<project_id>"
// set endpoint with OTEL_EXPORTER_OTLP_ENDPOINT=https://<endpoint>
// set OTEL_EXPORTER_OTLP_HEADERS="x-goog-user-project=<project_id>"
exporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds)))
if err != nil {
  panic(err)
}

// Other OpenTelemetry configuration remains unaffected.

    Python

    En esta sección se muestran los cambios que debes hacer al usar gRPC para la exportación. Si usas datos codificados con protobuf a través de conexiones HTTP para la exportación, usa las credenciales predeterminadas. También debes proporcionar estas credenciales cuando crees una instancia de BatchSpanProcessor. Para obtener más información, consulta Aplicación Python.

    En una aplicación Python que use gRPC para la exportación, añade las siguientes importaciones:

    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

    Además, actualiza el código de inicialización para configurar ADC antes de crear una instancia del exportador de gRPC:

    credentials, _ = google.auth.default()
request = google.auth.transport.requests.Request()
resource = Resource.create(attributes={SERVICE_NAME: "otlp-gcp-grpc-sample"})

auth_metadata_plugin = AuthMetadataPlugin(credentials=credentials, request=request)
channel_creds = grpc.composite_channel_credentials(
    grpc.ssl_channel_credentials(),
    grpc.metadata_call_credentials(auth_metadata_plugin),
)

# Configure the TraceProvider

    Node.js

    En esta sección se muestran los cambios que debes hacer al usar gRPC para la exportación. Si usas datos codificados con protobuf en conexiones HTTP para la exportación, los cambios que debes hacer son ligeramente diferentes a los que se describen aquí. Para obtener más información, consulta el archivo app-http-proto-export.ts que se incluye en la aplicación Node.js.

    En una aplicación Node.js que use gRPC para la exportación, añade las siguientes importaciones:

    import {AuthClient, GoogleAuth} from 'google-auth-library';
import {credentials} from '@grpc/grpc-js';

    Además, actualiza el código de inicialización para configurar ADC antes de crear una instancia del exportador de gRPC:

    async function getAuthenticatedClient(): Promise<AuthClient> {
  const auth: GoogleAuth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/cloud-platform',
  });
  return await auth.getClient();
}

// Express App that exports traces via gRPC with protobuf
async function main() {
  const authenticatedClient: AuthClient = await getAuthenticatedClient();

  // Configure the TraceExporter
}

    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"

    Si usas Java y configuras tu aplicación para que use la extensión de autenticación de Google Cloud, como hace la aplicación Java de ejemplo, no es necesario que definas el ID del proyecto como parte de los atributos de recursos de OpenTelemetry. Sin embargo, definir este atributo no es perjudicial.

    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 especificar el proyecto de cuota cuando se usa 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.

    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

    Si usas Java y el módulo de configuración automática, puedes definir el endpoint del exportador mediante propiedades del sistema, como hace la aplicación de muestra de Java. No es necesario definir la variable de entorno del exportador para esa configuración.

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