Migrar do exportador de rastreamento para o endpoint OTLP

Este documento descreve como migrar um aplicativo instrumentado com o OpenTelemetry e que depende de exportadores Google Cloud para usar os exportadores OTLP do OpenTelemetry. Ambas as configurações enviam telemetria para seu projeto do Google Cloud. As etapas neste documento são para a exportação em processo realizada pelo SDK do OpenTelemetry.

Este documento descreve como exportar dados de rastreamento ao usar a instrumentação manual. Esta orientação, fornecida para Java, Go e Python, não se aplica ao envio de dados de registro ou métrica para seu projeto do Google Cloud.

Por que migrar

Os SDKs do OpenTelemetry geram dados de registro, métrica e rastro no formato OTLP. Quando um aplicativo exporta esses dados para um projeto do Google Cloud usando um exportador Google Cloud , ele executa as seguintes etapas:

  1. Transforma os dados gravados do formato OTLP em um formato proprietário definido pela API Cloud Logging, pela API Cloud Monitoring ou pela API Cloud Trace.
  2. Envia os dados transformados para a API apropriada, que é armazenada no seu projeto do Google Cloud.

Para dados de rastreamento, recomendamos migrar seu aplicativo para usar a API Telemetry (OTLP) para exportar dados, porque essa exportação não exige uma transformação de dados. A transformação de dados pode causar a perda de alguns dados. Por exemplo, o formato proprietário pode ter limites mais baixos para determinados campos, ou alguns campos do OLTP podem não ser mapeados para um campo no formato proprietário.

Guia de migração para instrumentação manual

Esta seção descreve como modificar seu aplicativo para que ele envie os dados de rastreamento para seu projeto do Google Cloud usando a API Telemetry. Não é possível enviar dados de métricas ou registros para esse endpoint.

Adicionar dependências

A primeira etapa é adicionar dependências para o exportador de rastros OTLP do OpenTelemetry no aplicativo. Selecione as versões de dependência adequadas para o aplicativo e o sistema de build.

Java

Para um aplicativo Java que usa o sistema de build do Gradle:

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

Go

Para um aplicativo Golang, verifique se o arquivo go.mod tem as seguintes dependências:

// 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 um aplicativo Python, instale as seguintes dependências ou atualize o arquivo 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

Substituir o uso de exportadores de Google Cloud por exportadores OTLP

Atualize o código do aplicativo para que o SDK do OpenTelemetry seja configurado para usar os exportadores OTLP do OpenTelemetry em vez do exportador de rastros Google Cloud . As mudanças necessárias são específicas 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)

Configurar a autenticação

Com as mudanças anteriores na configuração do SDK do OpenTelemetry, seu aplicativo é configurado para exportar rastros usando os exportadores OTLP do OpenTelemetry com gRPC ou HTTP. Em seguida, configure as exportações para enviar esses rastros ao seu projeto do Google Cloud.

Para configurar a autenticação, faça o seguinte:

  1. Configure cabeçalhos de autenticação para as chamadas de exportação.
  2. Configure os atributos de recurso do OpenTelemetry e os cabeçalhos OTLP necessários.
  3. Configure o endpoint do exportador.

Esta seção detalha cada uma dessas etapas.

Configurar cabeçalhos de autenticação para as chamadas de exportação

Para configurar o exportador com as credenciais padrão do aplicativo (ADC) Google Cloud, adicione uma biblioteca do Google Auth específica para a linguagem.

Java

Para autenticar na Observabilidade do Google Cloud, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

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

Go

Para autenticar na Observabilidade do Google Cloud, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 autenticar na Observabilidade do Google Cloud, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

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

Em seguida, atualize o código do aplicativo que constrói o exportador de período do OTLP para que ele adicione os tokens de autorização recuperados da biblioteca aos cabeçalhos. Essa etapa é específica da linguagem, mas a implementação é semelhante para todos os idiomas.

Java

Recomendamos o uso da extensão de autenticação do Google Cloud quando você estiver usando o módulo de autoconfiguração do SDK do OpenTelemetry. Para conferir um exemplo completo que usa essa extensão, consulte Exemplo de rastro OTLP com autenticação do 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

Configurar os atributos de recurso do OpenTelemetry e os cabeçalhos OTLP necessários

Defina as seguintes variáveis de ambiente do OpenTelemetry:

  • OTEL_RESOURCE_ATTRIBUTES: configure essa variável de ambiente para definir a chave gcp.project_id nos atributos do recurso do OpenTelemetry. Defina o valor como o ID do seu projeto do Google Cloud.

  • OTEL_EXPORTER_OTLP_HEADERS: configure essa variável de ambiente para adicionar o cabeçalho x-goog-user-project. O valor precisa ser o ID do seu projeto do Google Cloud em que a cota de serviço será consumida. Normalmente, o valor é definido como o mesmo da chave gcp.project_id.

Exemplo:

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

Para mais informações sobre as variáveis de ambiente do OpenTelemetry, consulte Configuração geral do SDK.

Configurar o endpoint do exportador

Defina o valor da variável de ambiente OTEL_EXPORTER_OTLP_ENDPOINT como o endpoint OLTP para Google Cloud.

Exemplo:

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

Para mais informações sobre as variáveis de ambiente do OpenTelemetry, consulte Configuração geral do SDK.

Permissões necessárias

Há papéis e permissões do Identity and Access Management (IAM) que permitem que você ou uma conta de serviço gravem dados de rastreamento na API Telemetry e os armazenem no projeto do Google Cloud. Por exemplo, se você recebeu apenas papéis ou permissões do Cloud Trace, essas permissões não vão permitir que você grave dados usando a API Telemetry.

Para mais informações, consulte Como o Application Default Credentials funciona e Configurar o Application Default Credentials (ADC) para um ambiente de desenvolvimento local.

APIs necessárias

A API Telemetry fica desativada por padrão. É necessário ativar essa API. Confira a seguir informações sobre as APIs necessárias para enviar dados de telemetria a um projeto do Google Cloud e para visualizar esses dados:

Console do 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