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 Google Cloud esportatori per utilizzare gli esportatori OTTP 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 delle tracce quando utilizzi l'instrumentazione manuale. Queste indicazioni, fornite per Java, Go e Python, non si applicano all'invio di dati di log o metriche al progetto Google Cloud.

Perché eseguire la migrazione

Gli SDK OpenTelemetry generano dati di log, metriche e tracce nel formato OTLP. Quando un'applicazione esporta questi dati in un progetto Google Cloud utilizzando un Google Cloud esportatore, 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'API Cloud Trace.
  2. Invia i dati trasformati all'API appropriata, che vengono poi memorizzati nel tuo progetto Google Cloud.

Per i dati traccia, ti consigliamo di eseguire la migrazione dell'applicazione in modo che utilizzi l'API Telemetry (OTLP) per esportare i dati, in quanto 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 o alcuni campi OTLP potrebbero non essere mappati a un campo nel formato proprietario.

Guida alla migrazione per la misurazione manuale

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

Aggiungi le 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 tuo sistema di compilazione.

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'uso 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 OTLP di OpenTelemetry anziché l' Google Cloud esportatore di tracce. 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 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 le esportazioni per inviare le 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 delle risorse 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 il linguaggio.

Java

Per autenticarti in Trace, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare 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 Trace, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare 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 Trace, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

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

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

Java

Ti consigliamo di utilizzare la Estensione di autenticazione Google Cloud quando utilizzi il modulo di configurazione automatica dell'SDK OpenTelemetry. Per un esempio completo che utilizza questa estensione, consulta Esempio di traccia OTLP con 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(() -> {
                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

Configura gli attributi delle risorse OpenTelemetry e le intestazioni OTLP richiesti

Imposta le seguenti variabili di ambiente OpenTelemetry:

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

  • OTEL_EXPORTER_OTLP_HEADERS: configura questa variabile di ambiente per aggiungere l'intestazione x-goog-user-project. Il valore deve essere l'ID del progetto Google Cloud da cui verrà consumata la quota del servizio. In genere, il valore è impostato sullo stesso valore della chiave gcp.project_id.

Esempio:

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

Per ulteriori informazioni sulle variabili di ambiente OpenTelemetry, consulta 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.

Autorizzazioni obbligatorie

Esistono ruoli e autorizzazioni di Identity and Access Management (IAM) che ti consentono, o consentono a un account di servizio, di scrivere i dati di traccia nell'API Telemetry e di archiviarli nel tuo progetto Google Cloud. Ad esempio, se ti sono stati concessi solo ruoli o autorizzazioni Cloud Trace, queste autorizzazioni non ti consentono di scrivere dati utilizzando l'API Telemetry.

  • Per ottenere le autorizzazioni necessarie per consentire alle applicazioni di esempio di scrivere dati di log, metriche e traccia, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

Per ulteriori informazioni, consulta Come funzionano le credenziali predefinite dell'applicazione e Configurare le credenziali predefinite dell'applicazione (ADC) per un ambiente di sviluppo locale.

API obbligatorie

L'API Telemetry è disabilitata per impostazione predefinita. Devi abilitare questa API. Di seguito sono riportate informazioni sulle API necessarie per inviare dati di telemetria a un progetto Google Cloud e per visualizzarli:

Console 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