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 intégrée 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 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.

Remarque : L'API Telemetry n'accepte que les données de trace. Vous ne pouvez pas envoyer de données de métriques ni de journaux à votre projet Google Cloud à l'aide de ce point de terminaison.

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 IAM (Identity and Access Management) requis. Vous devrez peut-être également attribuer des rôles IAM à un compte de service.

Activer la facturation et l'API Telemetry

Remarque : L'API Telemetry est désactivée par défaut.

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

Configurer les autorisations

• Pour obtenir les autorisations nécessaires pour permettre à l'application exemple d'envoyer des données de journaux, de métriques et de trace à votre projet, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

  • Rédacteur de traces de télémétrie cloud (roles/telemetry.tracesWriter)
  • Rédacteur de journaux (roles/logging.logWriter)
  • Rédacteur de métriques Monitoring (roles/monitoring.metricWriter)
  Remarque : Si vous configurez votre application de sorte que les Identifiants par défaut de l'application (ADC) s'appuient sur un compte de service, accordez les rôles IAM précédents au compte de service. Pour en savoir plus, consultez 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.

• Pour obtenir les autorisations nécessaires pour afficher vos données de journaux, de métriques et de traces, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

  • Lecteur de journaux (roles/logging.viewer)
  • Lecteur Monitoring (roles/monitoring.viewer)
  • Utilisateur Cloud Trace (roles/cloudtrace.user)

  Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

  Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

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, que ce soit avec 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 ressource OpenTelemetry requis

Ajoutez à la variable d'environnement OTEL_RESOURCE_ATTRIBUTES la paire clé-valeur qui spécifie votre projet. Pour la clé, utilisez gcp.project_id. Pour la valeur, utilisez 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.

Définir l'ID du projet de quota

Le projet de quota est le projet Google Cloud qui suit votre utilisation des requêtes API. Étant donné que l'API Telemetry est une API basée sur le client, la façon dont vous vous authentifiez détermine si le projet de quota est automatiquement identifié. Par exemple, vous n'avez pas besoin de spécifier le projet de quota lorsque vous utilisez un compte de service pour l'authentification. Toutefois, vous devez spécifier le projet de quota lorsque des identifiants utilisateur sont utilisés pour l'authentification.

Vous pouvez définir un projet de quota à l'aide d'une variable d'environnement. Pour déterminer la variable d'environnement à définir pour votre langage de programmation, consultez Définir le projet de quota à l'aide d'une variable d'environnement.

Par exemple, pour Go, vous pouvez définir le projet de quota comme suit :

export GOOGLE_CLOUD_QUOTA_PROJECT="QUOTA_PROJECT_ID"

Pour savoir comment résoudre les erreurs d'authentification, consultez Les identifiants utilisateur ne fonctionnent pas.

Remarque : Ne mettez pas à jour la variable d'environnement OTEL_EXPORTER_OTLP_HEADERS avec une paire clé/valeur qui utilise la clé x-goog-user-project. Cette configuration peut entraîner des valeurs en double dans la requête, ce qui provoque l'échec des commandes API.

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.