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 processus effectuée par le SDK OpenTelemetry.

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

Pourquoi migrer

Les SDK OpenTelemetry génèrent des données de journal, de métrique et de trace au format OTLP. Lorsqu'une application exporte ces données vers un projet Google 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 sont ensuite stockées dans votre projet Google Cloud.

Pour les données de trace, nous vous recommandons de migrer votre application vers l'API Telemetry (OTLP) afin d'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 OLTP peuvent ne pas être mappés sur un champ au format propriétaire.

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étrique ou de journal à ce point de terminaison.

Ajouter des dépendances

La première étape consiste à ajouter des dépendances pour l'exportateur de traces OTLP d'OpenTelemetry dans votre application. Sélectionnez les versions de dépendance appropriées pour 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 les 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' Google Cloud exportateur de traces. Les modifications requises sont spécifiques à 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

Avec les modifications précédentes apportées à la configuration du SDK OpenTelemetry, votre application est configurée pour exporter des traces à l'aide des exportateurs OTLP OpenTelemetry à l'aide de gRPC ou HTTP. Vous devez ensuite configurer les exportations 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, modifiez le code de l'application qui crée l'exportateur de délais OTLP afin qu'il ajoute les jetons d'autorisation récupérés dans la bibliothèque aux en-têtes. Cette étape est spécifique à chaque 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 de configuration automatique du SDK OpenTelemetry. Pour obtenir un exemple complet qui utilise cette extension, consultez Exemple de trace OTLP avec l'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(() -> {
                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

Configurer les attributs de ressource 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 être l'ID de votre projet Google Cloud.

  • OTEL_EXPORTER_OTLP_HEADERS: configurez cette variable d'environnement pour ajouter l'en-tête x-goog-user-project. La valeur doit correspondre à l'ID de votre projet Google Cloud à partir duquel le quota de service sera consommé. En règle générale, la valeur est définie sur la même valeur que pour la clé gcp.project_id.

Exemple :

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

Pour en savoir plus sur les variables d'environnement OpenTelemetry, consultez la section 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 la section Configuration générale du SDK.

Autorisations requises

Des rôles et des autorisations IAM (Identity and Access Management) vous permettent, ou à un compte de service, d'écrire des données de trace dans l'API Telemetry et de les stocker dans votre projet Google Cloud. Par exemple, si vous n'avez reçu que des rôles ou des autorisations Cloud Trace, ces autorisations ne vous permettront pas d'écrire des données à l'aide de l'API Telemetry.

Pour en savoir plus, consultez les pages Fonctionnement des identifiants par défaut de l'application et Configurer les identifiants par défaut de l'application (ADC) pour un environnement de développement local.

API requises

L'API Telemetry est désactivée par défaut. Vous devez activer cette API. Vous trouverez ci-dessous des informations sur les API requises pour envoyer des données de télémétrie à un projet Google Cloud et pour afficher ces données:

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