Migrar do exportador de rastreamento para o endpoint OTLP

Neste documento, descrevemos como migrar um aplicativo instrumentado com o OpenTelemetry e que depende de exportadores Google Cloud para usar os exportadores OTLP do OpenTelemetry. As duas configurações enviam telemetria para o projeto Google Cloud . As etapas neste documento são para a exportação no processo realizada pelo SDK do OpenTelemetry.

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

Por que migrar

Os SDKs do OpenTelemetry geram dados de registros, métricas e traces no formato OTLP. Quando um aplicativo exporta esses dados para um projeto usando um exportador, ele realiza as seguintes etapas:Google Cloud Google Cloud

  1. Transforma os dados gravados do formato OTLP em um formato proprietário definido pela API Cloud Logging, API Cloud Monitoring ou API Cloud Trace.
  2. Envia os dados transformados para a API apropriada, que é armazenada no projeto 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 algumas informações. Por exemplo, o formato proprietário pode ter limites menores para determinados campos, ou alguns campos do OTLP podem não ser mapeados para um campo no formato proprietário.

Antes de começar

Antes de migrar seu aplicativo para enviar dados de rastreamento ao endpoint OTLP, ative a API Telemetry e verifique se você recebeu os papéis necessários do Identity and Access Management (IAM). Talvez seja necessário conceder papéis do IAM a uma conta de serviço.

Ativar a API Telemetry

Verifique se a API Telemetry, a API Cloud Logging, a API Cloud Monitoring e a API Cloud Trace estão ativadas para seu projeto. A API Telemetry fica desativada por padrão.

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

Configurar permissões

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

Nesta seção, descrevemos como modificar seu aplicativo para que ele envie os dados de rastreamento ao projeto 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 rastreamento OTLP do OpenTelemetry no seu aplicativo. Selecione as versões de dependência adequadas para seu aplicativo e 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 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 rastreamento Google Cloud . As mudanças necessárias são específicas do 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 está configurado para exportar rastreamentos usando os exportadores OTLP do OpenTelemetry com gRPC ou HTTP. Em seguida, configure os exportadores para enviar esses rastreamentos ao seu projeto 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 suas Google Cloud Application Default Credentials (ADC), adicione uma biblioteca de autenticação do Google específica para uma linguagem.

Java

Para autenticar no Google Cloud Observability, 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 no Google Cloud Observability, 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 no Google Cloud Observability, 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 cria o exportador de intervalos OTLP para que ele adicione os tokens de autorização recuperados da biblioteca aos cabeçalhos. Essa etapa é específica de cada linguagem, mas a implementação é semelhante para todas elas.

Java

Recomendamos que você use a extensão de autenticação do Google Cloud ao usar o módulo de autoconfiguração do SDK OpenTelemetry. Para um exemplo completo que usa essa extensão, consulte Exemplo de rastreamento 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(
                () -> {
                  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 os atributos de recurso e cabeçalhos OTLP necessários do OpenTelemetry

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 de recurso do OpenTelemetry. Defina o valor como o ID do seu projeto Google Cloud .

Exemplo:

export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=PROJECT_ID"

Para mais informações sobre 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 do OTLP para Google Cloud.

Exemplo:

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

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