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. Estas orientações, que são fornecidas para Java, Go e Python, não se aplicam ao envio de dados de registro ou métricas para seu projeto 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 Google Cloud exportador, ele realiza as seguintes etapas: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 seu 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.

Observação: a API Telemetry aceita apenas dados de rastreamento. Não é possível enviar dados de métricas ou de registros para seu projeto Google Cloud usando esse endpoint.

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 o faturamento e a API Telemetry

Observação: a API Telemetry fica desativada por padrão.

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

Configurar permissões

• Para receber as permissões necessárias para permitir que o aplicativo de exemplo envie dados de registros, métricas e rastreamentos ao seu projeto, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

  • Gravador de traces de telemetria do Cloud (roles/telemetry.tracesWriter)
  • Gravador de registros (roles/logging.logWriter)
  • Gravador de métricas do Monitoring (roles/monitoring.metricWriter)
  Observação: se você configurar o aplicativo para que as Application Default Credentials (ADC) dependam de uma conta de serviço, conceda as funções do IAM anteriores à conta de serviço. Para mais informações, consulte Como o Application Default Credentials funciona e Configurar o Application Default Credentials (ADC) para um ambiente de desenvolvimento local.

• Para ter as permissões necessárias para visualizar seus dados de registros, métricas e rastreamentos, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

  • Visualizador de registros (roles/logging.viewer)
  • Leitor do Monitoring (roles/monitoring.viewer)
  • Usuário do Cloud Trace (roles/cloudtrace.user)

  Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

  Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

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 de 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 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 recursos 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 obrigatórios do OpenTelemetry

Adicione à variável de ambiente OTEL_RESOURCE_ATTRIBUTES o par de chave-valor que especifica seu projeto. Para a chave, use gcp.project_id. Para o valor, use 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.

Definir o ID do projeto de cota

O projeto de cota é o projeto Google Cloud que rastreia seu uso de solicitações de API. Como a API Telemetry é uma API baseada em cliente, a forma de autenticação determina se o projeto de cota é identificado automaticamente. Por exemplo, não é necessário especificar o projeto de cota ao usar uma conta de serviço para autenticação. No entanto, é necessário especificar o projeto de cota quando as credenciais do usuário são usadas para autenticação.

É possível definir um projeto de cota usando uma variável de ambiente. Para determinar qual variável de ambiente definir para sua linguagem de programação, consulte Definir o projeto de cota usando uma variável de ambiente.

Por exemplo, em Go, você pode definir o projeto de cota da seguinte maneira:

export GOOGLE_CLOUD_QUOTA_PROJECT="QUOTA_PROJECT_ID"

Para informações sobre como resolver erros de autenticação, consulte Credenciais do usuário que não funcionam.

Observação: não atualize a variável de ambiente OTEL_EXPORTER_OTLP_HEADERS com um par de chave-valor que use a chave x-goog-user-project. Essa configuração pode resultar em valores duplicados na solicitação, o que causa falha nos comandos da API.

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.