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 tracce 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.

Nota :l'API Telemetry accetta solo i dati di traccia. Non puoi inviare dati di metriche o log al tuo progetto Google Cloud utilizzando questo endpoint.

Prima di iniziare

Prima di eseguire la migrazione dell'applicazione per inviare dati di traccia all'endpoint OTLP, abilita 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 la fatturazione e l'API Telemetry

Nota: l'API Telemetry è disattivata per impostazione predefinita.

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

Configura autorizzazioni

• Per ottenere le autorizzazioni necessarie per consentire all'applicazione di esempio di inviare dati di log, metriche e tracce al tuo progetto, chiedi all'amministratore di concederti i seguenti ruoli IAM nel tuo progetto:

  • Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)
  • Logs Writer (roles/logging.logWriter)
  • Monitoring Metric Writer (roles/monitoring.metricWriter)
  Nota :se configuri l'applicazione in modo che le Credenziali predefinite dell'applicazione (ADC) si basino su un account di servizio, allora concedi i ruoli IAM precedenti al account di servizio. 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.

• Per ottenere le autorizzazioni necessarie per visualizzare i dati di log, metriche e tracce, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto:

  • Visualizzatore log (roles/logging.viewer)
  • Monitoring Viewer (roles/monitoring.viewer)
  • Utente Cloud Trace (roles/cloudtrace.user)

  Per ulteriori informazioni sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

  Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Guida alla migrazione per l'instrumentazione manuale

Questa sezione descrive come modificare l'applicazione in modo che invii i dati di tracciamento 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 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'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 richieste.
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 eseguire l'autenticazione 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 eseguire l'autenticazione 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 eseguire l'autenticazione 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 delle risorse OpenTelemetry richiesti

Aggiungi alla variabile di ambiente OTEL_RESOURCE_ATTRIBUTES la coppia chiave-valore che specifica il tuo progetto. Per la chiave, utilizza gcp.project_id. Per il valore, utilizza l'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.

Imposta l'ID progetto quota

Il progetto quota è il progetto Google Cloud che monitora l'utilizzo delle richieste API. Poiché l'API Telemetry è un'API basata sul client, la modalità di autenticazione determina se il progetto di quota viene identificato automaticamente. Ad esempio, non devi specificare il progetto quota quando utilizzi unaccount di serviziot per l'autenticazione. Tuttavia, devi specificare il progetto di quota quando le credenziali utente vengono utilizzate per l'autenticazione.

Puoi impostare un progetto di quota utilizzando una variabile di ambiente. Per determinare quale variabile di ambiente impostare per il tuo linguaggio di programmazione, consulta Impostare il progetto di quota utilizzando una variabile di ambiente.

Ad esempio, per Go puoi impostare il progetto di quota nel seguente modo:

export GOOGLE_CLOUD_QUOTA_PROJECT="QUOTA_PROJECT_ID"

Per informazioni su come risolvere gli errori di autenticazione, vedi Le credenziali utente non funzionano.

Nota: non aggiornare la variabile di ambiente OTEL_EXPORTER_OTLP_HEADERS con una coppia chiave-valore che utilizza la chiave x-goog-user-project. Questa configurazione può comportare valori duplicati nella richiesta e ciò causa l'esito negativo dei comandi API.

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.