Esegui la migrazione dall'esportatore di traccia all'endpoint OTLP

Questo documento descrive come eseguire la migrazione di un'applicazione instrumentata con OpenTelemetry e che si basa su esportatori Google Cloud , per utilizzare gli esportatori OTLP di OpenTelemetry. Entrambe le configurazioni inviano la telemetria al tuo progetto Google Cloud . I passaggi descritti in questo documento riguardano l'esportazione in-process eseguita dall'SDK OpenTelemetry.

Questo documento descrive come esportare i dati di traccia quando utilizzi la strumentazione manuale. Queste indicazioni, fornite per Java, Go e Python, non si applicano all'invio di dati di log o metriche al tuo progetto Google Cloud .

Perché eseguire la migrazione

Gli SDK OpenTelemetry generano dati di log, metriche e traccia nel formato OTLP. Quando un'applicazione esporta questi dati in un progettoGoogle Cloud utilizzando un esportatore Google Cloud , quest'ultimo esegue i seguenti passaggi:

  1. Trasforma i dati registrati dal formato OTLP in un formato proprietario definito dall'API Cloud Logging, dall'API Cloud Monitoring o dall'Cloud Trace API.
  2. Invia i dati trasformati all'API appropriata, che vengono poi memorizzati nel tuo progetto Google Cloud .

Per i dati di tracciamento, ti consigliamo di eseguire la migrazione dell'applicazione per utilizzare l'API Telemetry (OTLP) per esportare i dati, perché questa esportazione non richiede una trasformazione dei dati. La trasformazione dei dati potrebbe causare la perdita di alcuni dati. Ad esempio, il formato proprietario potrebbe avere limiti inferiori per determinati campi oppure alcuni campi OTLP potrebbero non essere mappati a un campo nel formato proprietario.

Prima di iniziare

Prima di eseguire la migrazione dell'applicazione per inviare dati di traccia all'endpoint OTLP, attiva l'API Telemetry e assicurati di disporre dei ruoli Identity and Access Management (IAM) richiesti. Potresti anche dover concedere ruoli IAM a unaccount di serviziot.

Abilita l'API Telemetry

Assicurati che l'API Telemetry, l'API Cloud Logging, l'API Cloud Monitoring e l'Cloud Trace API siano abilitate per il tuo progetto. L'API Telemetry è disabilitata per impostazione predefinita.

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

Configura autorizzazioni

Guida alla migrazione per l'instrumentazione manuale

Questa sezione descrive come modificare l'applicazione in modo che invii i dati di traccia al tuo progetto Google Cloud utilizzando l'API Telemetry. Non puoi inviare dati di log o metriche a questo endpoint.

Aggiungere dipendenze

Il primo passaggio consiste nell'aggiungere le dipendenze per l'esportatore di tracce OTLP di OpenTelemetry nella tua applicazione. Seleziona le versioni delle dipendenze appropriate per la tua applicazione e il tuosistema di compilazioned.

Java

Per un'applicazione Java che utilizza il sistema di compilazione Gradle:

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

Go

Per un'applicazione Golang, assicurati che il file go.mod abbia le seguenti dipendenze:

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

Per un'applicazione Python, installa le seguenti dipendenze o aggiorna il file 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

Sostituisci l'utilizzo degli esportatori Google Cloud con gli esportatori OTLP

Aggiorna il codice dell'applicazione in modo che l'SDK OpenTelemetry sia configurato per utilizzare gli esportatori OpenTelemetry OTLP anziché l'esportatore di tracce Google Cloud . Le modifiche richieste sono specifiche per la lingua.

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)

Configura l'autenticazione

Con le modifiche precedenti alla configurazione dell'SDK OpenTelemetry, la tua applicazione è configurata per esportare le tracce utilizzando gli esportatori OTLP di OpenTelemetry tramite gRPC o HTTP. Successivamente, devi configurare gli esportatori per inviare queste tracce al tuo progetto Google Cloud .

Per configurare l'autenticazione:

  1. Configura le intestazioni di autenticazione per le chiamate di esportazione.
  2. Configura gli attributi della risorsa OpenTelemetry e le intestazioni OTLP richiesti.
  3. Configura l'endpoint dell'esportatore.

Questa sezione descrive in dettaglio ciascuno di questi passaggi.

Configura le intestazioni di autenticazione per le chiamate di esportazione

Per configurare l'esportatore con le tue Google Cloud credenziali predefinite dell'applicazione (ADC), aggiungi una libreria di autenticazione Google specifica per la lingua.

Java

Per autenticarti in Google Cloud Observability, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

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

Go

Per autenticarti in Google Cloud Observability, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

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

Per autenticarti in Google Cloud Observability, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

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

Successivamente, aggiorna il codice dell'applicazione che crea l'esportatore di span OTLP in modo che aggiunga i token di autorizzazione recuperati dalla libreria alle intestazioni. Questo passaggio è specifico per la lingua, ma l'implementazione è simile per tutte le lingue.

Java

Ti consigliamo di utilizzare l'estensione di autenticazione Google Cloud quando utilizzi il modulo di configurazione automatica dell'SDK OpenTelemetry. Per un esempio completo che utilizza questa estensione, vedi Traccia OTLP con esempio di autenticazione 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

Configura gli attributi della risorsa OpenTelemetry e le intestazioni OTLP richieste

Imposta le seguenti variabili di ambiente OpenTelemetry:

  • OTEL_RESOURCE_ATTRIBUTES: configura questa variabile di ambiente per impostare la chiave gcp.project_id negli attributi delle risorse OpenTelemetry. Imposta il valore sull'ID del tuo progetto Google Cloud .

Esempio:

export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=PROJECT_ID"

Per ulteriori informazioni sulle variabili di ambiente OpenTelemetry, consulta la sezione Configurazione generale dell'SDK.

Configura l'endpoint dell'esportatore

Imposta il valore della variabile di ambiente OTEL_EXPORTER_OTLP_ENDPOINT sull'endpoint OTLP per Google Cloud.

Esempio:

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

Per ulteriori informazioni sulle variabili di ambiente OpenTelemetry, consulta la sezione Configurazione generale dell'SDK.