Migre do exportador de rastreios para o ponto final OTLP

Este documento descreve como migrar uma aplicação que está instrumentada com o OpenTelemetry e depende de exportadores para usar os exportadores OTLP do OpenTelemetry. Google Cloud Ambas as configurações enviam telemetria para o seu Google Cloud projeto. Os passos neste documento destinam-se à exportação no processo realizada pelo SDK do OpenTelemetry.

Este documento descreve como exportar dados de rastreio quando usa a instrumentação manual. Estas orientações, fornecidas para Java, Go e Python, não se aplicam ao envio de dados de registo ou de métricas para o seu projeto Google Cloud .

Por que motivo deve migrar

Os SDKs OpenTelemetry geram dados de registo, métricas e rastreio no formato OTLP. Quando uma aplicação exporta esses dados para um Google Cloud projeto através de um Google Cloud exportador, esse exportador executa os seguintes passos:

  1. Transforma os dados registados do formato OTLP num 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 adequada, que são depois armazenados no seu projeto do Google Cloud .

Para dados de rastreio, recomendamos que migre a sua aplicação para usar a API Telemetry (OTLP) para exportar dados, porque esta exportação não requer 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 inferiores para determinados campos ou alguns campos OTLP podem não ser mapeados para um campo no formato proprietário.

Antes de começar

Antes de migrar a sua aplicação para enviar dados de rastreio para o ponto final OTLP, ative a API Telemetry e certifique-se de que lhe foram concedidas as funções de gestão de identidade e de acesso (IAM) necessárias. Também pode ter de conceder funções do IAM a uma conta de serviço.

Ative a faturação e a 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.

    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.

    Enable the APIs

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    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.

    Enable the APIs

    8.

    Configure autorizações

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

    Esta secção descreve como modificar a sua aplicação para que envie os dados de rastreio para o seu projeto do Google Cloud através da API Telemetry. Não pode enviar dados de métricas nem de registos para este ponto final.

    Adicione dependências

    O primeiro passo é adicionar dependências para o exportador de rastreio OTLP do OpenTelemetry na sua aplicação. Selecione as versões das dependências adequadas para a sua aplicação e sistema de compilação.

    Java

    Para uma aplicação Java que usa o sistema de compilação Gradle:

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

    Go

    Para uma aplicação Golang, certifique-se de que o ficheiro 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 uma aplicação Python, instale as seguintes dependências ou atualize o ficheiro 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

    Substitua a utilização de Google Cloud exportadores por exportadores OTLP

    Atualize o código da aplicação de forma que o SDK OpenTelemetry esteja configurado para usar os exportadores OTLP OpenTelemetry em vez do Google Cloud exportador de rastreio. As alterações 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)

    Configure a autenticação

    Com as alterações anteriores à configuração do SDK OpenTelemetry, a sua aplicação está configurada para exportar rastreios através dos exportadores OTLP OpenTelemetry usando gRPC ou HTTP. Em seguida, tem de configurar os exportadores para enviar esses rastreios para o seu Google Cloud projeto.

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

    1. Configure os 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 ponto final do exportador.

    Esta secção detalha cada um destes passos.

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

    Para configurar o exportador com as suas Google Cloud Credenciais padrão da aplicação (ADC), adicione uma biblioteca Google Auth específica do idioma.

    Java

    Para se autenticar no Trace, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 se autenticar no Trace, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 se autenticar no Trace, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 da aplicação que cria o exportador de intervalos OTLP para que adicione os tokens de autorização obtidos da biblioteca aos cabeçalhos. Este passo é específico do idioma, mas a implementação é semelhante para todos os idiomas.

    Java

    Recomendamos que use a extensão de autenticação do Google Cloud quando usar o módulo de configuração automática do SDK OpenTelemetry. Para ver um exemplo completo que usa esta extensão, consulte o artigo Exemplo de rastreio OTLP com autenticação 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

    Configure os atributos de recursos do OpenTelemetry necessários

    Adicione à variável de ambiente OTEL_RESOURCE_ATTRIBUTES o par chave-valor que especifica o seu projeto. Para a tecla, use gcp.project_id. Para o valor, use o ID do seu Google Cloud projeto.

    Exemplo:

    export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=PROJECT_ID"

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

    Defina o ID do projeto de quota

    O projeto de quota é o Google Cloud projeto que monitoriza a sua utilização de pedidos API. Uma vez que a API Telemetry é uma API baseada no cliente, a forma como se autentica determina se o projeto de quotas é identificado automaticamente. Por exemplo, não precisa de especificar o projeto de quota quando usa uma conta de serviço para autenticação. No entanto, tem de especificar o projeto de quota quando as credenciais do utilizador são usadas para autenticação.

    Pode definir um projeto de quota através de uma variável de ambiente. Para determinar que variável de ambiente definir para a sua linguagem de programação, consulte Defina o projeto de quota através de uma variável de ambiente.

    Por exemplo, para o Go, pode definir o projeto de quota da seguinte forma:

    export GOOGLE_CLOUD_QUOTA_PROJECT="QUOTA_PROJECT_ID"

    Para obter informações sobre como resolver erros de autenticação, consulte o artigo As credenciais do utilizador não funcionam.

    Configure o ponto final do exportador

    Defina o valor da variável de ambiente OTEL_EXPORTER_OTLP_ENDPOINT para o ponto final OTLP 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 a secção Configuração geral do SDK.