Migrer de l'exportateur de trace vers le point de terminaison OTLP

Ce document explique comment migrer une application instrumentée avec OpenTelemetry et qui s'appuie sur des exportateurs Google Cloud pour utiliser les exportateurs OTLP d'OpenTelemetry. Les deux configurations envoient des données de télémétrie à votre projet Google Cloud . Les étapes décrites dans ce document concernent l'exportation en cours de traitement effectuée par le SDK OpenTelemetry.

Ce document explique comment exporter des données de trace lorsque vous utilisez l'instrumentation manuelle. Ces conseils, qui sont fournis pour Java, Go et Python, ne s'appliquent pas à l'envoi de données de journaux ou de métriques à votre projet Google Cloud .

Pourquoi migrer ?

Les SDK OpenTelemetry génèrent des données de journaux, de métriques et de traces au format OTLP. Lorsqu'une application exporte ces données vers un projetGoogle Cloud à l'aide d'un exportateur Google Cloud , cet exportateur effectue les étapes suivantes :

  1. Transforme les données enregistrées au format OTLP en un format propriétaire défini par l'API Cloud Logging, l'API Cloud Monitoring ou l'API Cloud Trace.
  2. envoie les données transformées à l'API appropriée, qui les stocke ensuite dans votre projet Google Cloud .

Pour les données de trace, nous vous recommandons de migrer votre application afin d'utiliser l'API Telemetry (OTLP) pour exporter les données, car cette exportation ne nécessite pas de transformation des données. La transformation des données peut entraîner la perte de certaines données. Par exemple, le format propriétaire peut avoir des limites inférieures pour certains champs, ou certains champs OTLP peuvent ne pas correspondre à un champ du format propriétaire.

Avant de commencer

Avant de migrer votre application pour envoyer des données de trace au point de terminaison OTLP, activez l'API Telemetry et assurez-vous de disposer des rôles Identity and Access Management (IAM) requis. Vous devrez peut-être également attribuer des rôles IAM à un compte de service.

Activer l'API Telemetry

Assurez-vous que l'API Telemetry, l'API Cloud Logging, l'API Cloud Monitoring et l'API Cloud Trace sont activées pour votre projet. L'API Telemetry est désactivée par défaut.

Console Google Cloud

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

Configurer les autorisations

Guide de migration pour l'instrumentation manuelle

Cette section explique comment modifier votre application pour qu'elle envoie vos données de trace à votre projet Google Cloud à l'aide de l'API Telemetry. Vous ne pouvez pas envoyer de données de métriques ni de journaux à ce point de terminaison.

Ajouter des dépendances

La première étape consiste à ajouter des dépendances pour l'exportateur de trace OTLP d'OpenTelemetry dans votre application. Sélectionnez les versions de dépendances adaptées à votre application et à votre système de compilation.

Java

Pour une application Java utilisant le système de compilation Gradle :

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

Go

Pour une application Golang, assurez-vous que le fichier go.mod comporte les dépendances suivantes :

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

Pour une application Python, installez les dépendances suivantes ou mettez à jour le fichier 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

Remplacer l'utilisation des exportateurs Google Cloud par des exportateurs OTLP

Mettez à jour le code de votre application afin que le SDK OpenTelemetry soit configuré pour utiliser les exportateurs OTLP OpenTelemetry au lieu de l'exportateur de trace Google Cloud . Les modifications requises dépendent de la langue.

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)

Configurer l'authentification

Grâce aux modifications apportées à la configuration du SDK OpenTelemetry, votre application est configurée pour exporter des traces à l'aide des exportateurs OTLP OpenTelemetry utilisant gRPC ou HTTP. Ensuite, vous devez configurer les exportateurs pour envoyer ces traces à votre projet Google Cloud .

Pour configurer l'authentification, procédez comme suit :

  1. Configurez les en-têtes d'authentification pour les appels d'exportation.
  2. Configurez les attributs de ressources OpenTelemetry et les en-têtes OTLP requis.
  3. Configurez le point de terminaison de l'exportateur.

Cette section détaille chacune de ces étapes.

Configurer les en-têtes d'authentification pour les appels d'exportation

Pour configurer l'exportateur avec vos Google Cloud identifiants par défaut de l'application (ADC), ajoutez une bibliothèque d'authentification Google spécifique à la langue.

Java

Pour vous authentifier auprès de Google Cloud Observability, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 

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

Go

Pour vous authentifier auprès de Google Cloud Observability, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement 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

Pour vous authentifier auprès de Google Cloud Observability, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 

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

Ensuite, mettez à jour le code de l'application qui construit l'exportateur de spans OTLP afin qu'il ajoute les jetons d'autorisation récupérés à partir de la bibliothèque aux en-têtes. Cette étape est spécifique à un langage, mais l'implémentation est semblable pour tous les langages.

Java

Nous vous recommandons d'utiliser l'extension d'authentification Google Cloud lorsque vous utilisez le module Autoconfigure du SDK OpenTelemetry. Pour obtenir un exemple complet utilisant cette extension, consultez Exemple de trace OTLP avec authentification 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

Configurer les attributs de ressources OpenTelemetry et les en-têtes OTLP requis

Définissez les variables d'environnement OpenTelemetry suivantes :

  • OTEL_RESOURCE_ATTRIBUTES : configurez cette variable d'environnement pour définir la clé gcp.project_id dans les attributs de ressource OpenTelemetry. La valeur doit correspondre à l'ID de votre projet Google Cloud .

Exemple :

export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=PROJECT_ID"

Pour en savoir plus sur les variables d'environnement OpenTelemetry, consultez Configuration générale du SDK.

Configurer le point de terminaison de l'exportateur

Définissez la valeur de la variable d'environnement OTEL_EXPORTER_OTLP_ENDPOINT sur le point de terminaison OTLP pour Google Cloud.

Exemple :

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

Pour en savoir plus sur les variables d'environnement OpenTelemetry, consultez Configuration générale du SDK.