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

Vous pouvez migrer des applications Java, Go, Python et Node.js instrumentées manuellement d'un exportateur de traces Google Cloud vers un exportateur OTLP OpenTelemetry en cours de traitement. L'exportateur OTLP envoie les données de trace directement à l'API Telemetry (OTLP) de votre projet Google Cloud à l'aide des protocoles d'exportation compatibles (gRPC ou http/protobuf).

Cette configuration n'exporte que les données de trace et ne s'applique qu'aux exportateurs en cours de traitement. Si votre application utilise un collecteur OpenTelemetry, consultez Exemples d'instrumentation basée sur un collecteur et Collecteur OpenTelemetry conçu par Google.

Pourquoi migrer ?

Les SDK OpenTelemetry génèrent des données de journaux, de métriques et de traces dans un format généralement cohérent avec les fichiers proto définis par le protocole OpenTelemetry. Toutefois, les champs peuvent être convertis d'un type de données spécifique à OpenTelemetry en un type de données JSON avant le stockage.

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

Échantillons disponibles

Les exemples d'applications référencés sur cette page sont disponibles sur GitHub. La plupart des applications sont configurées pour exporter des données de trace à l'aide de gRPC, ce qui signifie qu'elles envoient des données encodées en protobuf au format filaire gRPC via des connexions HTTP/2. Un exemple de code est également fourni pour les applications configurées pour exporter des données de trace en tant que données encodées en protobuf via des connexions HTTP :

  • Application Java

    L'exemple d'application est configuré pour exporter des traces sous forme de données encodées en protobuf via des connexions HTTP. Si vous préférez utiliser gRPC, l'instrumentation de cet exemple est applicable. Toutefois, vous devez modifier les propriétés système utilisées par le module de configuration automatique. L'exemple d'application spécifie l'exportateur http/protobuf. Pour utiliser gRPC, définissez ce paramètre sur grpc.

    Nous vous recommandons d'utiliser le module de configuration automatique du SDK OpenTelemetry pour configurer le SDK dans vos applications Java, comme l'application exemple.

  • Application Go utilisant gRPC et Application Go utilisant HTTP

    Il existe deux dépôts Go. Dans un dépôt, l'exemple d'application utilise gRPC. L'exemple de l'autre dépôt utilise des données encodées en protobuf sur des connexions HTTP.

  • Dépôt Python

    Ce dépôt contient deux exemples : un pour gRPC et un autre qui utilise des données encodées en protobuf sur des connexions HTTP.

  • Application Node.js

    Ce dépôt contient deux exemples : un pour gRPC et un autre qui utilise des données encodées en protobuf sur des connexions HTTP.

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 aussi attribuer des rôles IAM à un compte de service.

Activer la facturation et l'API Telemetry

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

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.

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, ajoutez les dépendances suivantes dans votre script build.gradle :

implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.62.0")
implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:1.62.0")

Go

Cette section illustre les modifications que vous devez apporter à vos dépendances lorsque vous utilisez gRPC pour l'exportation. Si vous utilisez des données encodées en protobuf sur des connexions HTTP pour l'exportation, incluez le package otlptracehttp en tant que dépendance. Pour en savoir plus, consultez Application Go utilisant HTTP.

Pour une application Go qui utilise gRPC pour l'exportation, mettez à jour le fichier go.mod pour inclure la dépendance suivante :

require (
	// ...
	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.44.0
)

Python

Cette section illustre les modifications que vous devez apporter à vos dépendances lorsque vous utilisez gRPC pour l'exportation. Si vous utilisez des données encodées en protobuf sur des connexions HTTP pour l'exportation, incluez le package opentelemetry-exporter-otlp-proto-http comme exigence. Pour en savoir plus, consultez le dépôt Python.

Pour une application Python qui utilise gRPC pour l'exportation, installez les dépendances suivantes ou mettez à jour le fichier requirements.txt :

opentelemetry-exporter-otlp-proto-grpc==1.42.1
grpcio==1.80.0

Node.js

Cette section illustre les modifications que vous devez apporter à vos dépendances lorsque vous utilisez gRPC pour l'exportation. Si vous utilisez des données encodées en protobuf sur des connexions HTTP pour l'exportation, incluez le package @opentelemetry/exporter-trace-otlp-proto en tant que dépendance. Pour en savoir plus, consultez Application Node.js.

Pour une application Node.js qui exporte des données de trace à l'aide de gRPC, ajoutez les dépendances suivantes :

"@opentelemetry/exporter-trace-otlp-grpc": "0.221.0",
"@grpc/grpc-js": "1.14.4"

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

Mettez à jour le code de votre application de sorte que le SDK OpenTelemetry soit configuré pour utiliser les exportateurs OTLP OpenTelemetry au lieu d'un exportateur de traces Google Cloud . Les modifications requises sont spécifiques à chaque langage.

Java

Pour une application Java, procédez comme suit :

  1. Ajoutez les instructions d'importation suivantes :

    import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;

  2. Mettez à jour le code de l'application pour utiliser le module de configuration automatique du SDK OpenTelemetry afin de configurer le SDK :

    public static void main(String[] args) {
  // Configure the OpenTelemetry pipeline with Auto configuration
  openTelemetrySdk = AutoConfiguredOpenTelemetrySdk.initialize().getOpenTelemetrySdk();

  // ...
}

  3. Configurez les propriétés système que le module de configuration automatique utilise au moment de l'exécution. Ce module utilise ces propriétés pour amorcer le SDK. Vous pouvez également utiliser des variables d'environnement au lieu de propriétés système. Pour en savoir plus, consultez Variables d'environnement et propriétés système.

    L'exemple d'application définit les propriétés système dans le script build.gradle :

    // You can switch the desired protocol here by changing `otel.exporter.otlp.protocol`.
def autoconf_config = [
	'-Dotel.exporter.otlp.endpoint=https://telemetry.googleapis.com',
	'-Dotel.traces.exporter=otlp',
	'-Dotel.logs.exporter=none',
	'-Dotel.metrics.exporter=none',
	'-Dotel.service.name=otlptrace-example',
	'-Dotel.exporter.otlp.protocol=http/protobuf',
	'-Dotel.java.global-autoconfigure.enabled=true',
]

    Transmettez également la configuration en tant qu'arguments JVM :

    application {
	mainClassName = 'com.google.cloud.opentelemetry.samples.otlptrace.OTLPTraceExample'
	// Pass the config as JVM arguments to the Java application
	applicationDefaultJvmArgs = autoconf_config
}

    Si vous préférez exporter les données de trace à l'aide de gRPC, définissez le protocole OTLP sur grpc au lieu de http/protobuf.

Go

Cette section illustre les modifications que vous devez apporter lorsque vous utilisez gRPC pour l'exportation. Si vous utilisez des données encodées en protobuf sur des connexions HTTP pour l'exportation, vous devez importer le package otlptracehttp et configurer l'exportateur avec les options correspondantes. Pour en savoir plus, consultez Application Go qui utilise HTTP.

Pour une application Go qui utilise gRPC pour l'exportation, ajoutez les instructions d'importation suivantes :

import (
	"context"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"

	// ...
)

Mettez également à jour le code d'initialisation pour configurer TraceProvider avec l'exportateur gRPC :

// Initializes OpenTelemetry with OTLP exporters
ctx := context.Background()

// Configure gRPC client with Google Application Default Credentials
creds, err := oauth.NewApplicationDefault(ctx)
if err != nil {
	panic(err)
}

// set OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=<project_id>"
// set endpoint with OTEL_EXPORTER_OTLP_ENDPOINT=https://<endpoint>
// set OTEL_EXPORTER_OTLP_HEADERS="x-goog-user-project=<project_id>"
// Configure exporter to use the credentials
exporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds)))
if err != nil {
	panic(err)
}

tp := sdktrace.NewTracerProvider(
	// For this example code we use sdktrace.AlwaysSample sampler to sample all traces.
	// In a production application, use sdktrace.TraceIDRatioBased with a desired probability.
	sdktrace.WithSampler(sdktrace.AlwaysSample()),
	sdktrace.WithBatcher(exporter))

otel.SetTracerProvider(tp)

Python

Cette section illustre les modifications que vous devez apporter lorsque vous utilisez gRPC pour l'exportation. Si vous utilisez des données encodées en protobuf sur des connexions HTTP pour l'exportation, vous devez importer à partir du package opentelemetry.exporter.otlp.proto.http et configurer l'exportateur avec les options correspondantes. Pour en savoir plus, consultez le dépôt Python.

Pour une application Python qui utilise gRPC pour l'exportation, ajoutez les importations suivantes :

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
    OTLPSpanExporter,
)

Mettez également à jour le code d'initialisation pour configurer TraceProvider avec l'exportateur gRPC :

# Initialize OpenTelemetry with OTLP exporters
# channel_creds: configure Application Default Credentials
trace_provider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(
    OTLPSpanExporter(
        credentials=channel_creds,
        endpoint="https://telemetry.googleapis.com:443/v1/traces",
    )
)
trace_provider.add_span_processor(processor)
trace.set_tracer_provider(trace_provider)
tracer = trace.get_tracer("my.tracer.name")

Node.js

Cette section illustre les modifications que vous devez apporter lorsque vous utilisez gRPC pour l'exportation. Si vous utilisez des données encodées en protobuf sur des connexions HTTP pour l'exportation, importez le package @opentelemetry/exporter-trace-otlp-proto. Pour en savoir plus, consultez Application Node.js.

Pour une application Node.js qui utilise gRPC pour l'exportation, ajoutez les importations suivantes :

import {OTLPTraceExporter} from '@opentelemetry/exporter-trace-otlp-grpc';

Mettez également à jour le code d'initialisation pour configurer TraceProvider avec l'exportateur gRPC :

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    credentials: credentials.combineChannelCredentials(
      credentials.createSsl(),
      credentials.createFromGoogleCredential({
        async getRequestHeaders(
          url?: string,
        ): Promise<{[index: string]: string}> {
          const rawHeaders = await authenticatedClient.getRequestHeaders(url);
          return Object.fromEntries(rawHeaders.entries());
        },
      }),
    ),
  }),
});
sdk.start();

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 avec les exportateurs OTLP OpenTelemetry à l'aide de gRPC ou de HTTP. Vous devez ensuite configurer les exportateurs pour qu'ils envoient 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 ressource 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 identifiants par défaut de l'application (ADC) Google Cloud, ajoutez une bibliothèque d'authentification Google spécifique au langage.

Java

Pour une application Java qui utilise le module de configuration automatique du SDK OpenTelemetry, nous vous recommandons d'utiliser également l'extension d'authentification Google Cloud.

implementation("io.opentelemetry.contrib:opentelemetry-gcp-auth-extension:1.56.0-alpha")

Go

Pour une application Go qui utilise gRPC pour l'exportation, mettez à jour le fichier go.mod pour inclure la dépendance suivante :

// When using gRPC based OTLP exporter, the auth is built in.
google.golang.org/grpc v1.82.1

Pour une application Go qui utilise HTTP pour l'exportation, mettez à jour le fichier go.mod pour inclure la dépendance suivante :

// When using http based OTLP exporter, use explicit auth library
golang.org/x/oauth2 v0.36.0

Python

Pour une application Python, ajoutez les dépendances suivantes à votre fichier requirements.txt :

# Google Auth Library
google-auth==2.53.0

Node.js

Pour une application Node.js, ajoutez la dépendance suivante :

"google-auth-library": "10.5.0"

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

Java

Lorsque vous disposez d'une application Java qui utilise le module de configuration automatique du SDK OpenTelemetry et l'extension d'authentification Google Cloud, vous n'avez pas besoin d'effectuer d'étapes spéciales lors de l'initialisation de votre application. Le module autoconfigure effectue automatiquement les étapes nécessaires pour configurer les ADC.

Go

Cette section illustre les modifications que vous devez apporter lorsque vous utilisez gRPC pour l'exportation. Si vous utilisez des données encodées en protobuf sur des connexions HTTP pour l'exportation, vous devez importer le package otlptracehttp et configurer l'exportateur en tant qu'objet otlptracehttp. Pour en savoir plus, consultez Application Go qui utilise HTTP.

Pour une application Go qui utilise gRPC pour l'exportation, ajoutez les instructions d'importation suivantes :

"google.golang.org/grpc"
"google.golang.org/grpc/credentials/oauth"

Mettez également à jour le code d'initialisation pour configurer ADC avant d'instancier l'exportateur gRPC :

// Initializes OpenTelemetry with OTLP exporters
ctx := context.Background()

// Configure gRPC client with Google Application Default Credentials
creds, err := oauth.NewApplicationDefault(ctx)
if err != nil {
	panic(err)
}

// set OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=<project_id>"
// set endpoint with OTEL_EXPORTER_OTLP_ENDPOINT=https://<endpoint>
// set OTEL_EXPORTER_OTLP_HEADERS="x-goog-user-project=<project_id>"
// Configure exporter to use the credentials
exporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds)))
if err != nil {
	panic(err)
}

tp := sdktrace.NewTracerProvider(
	// For this example code we use sdktrace.AlwaysSample sampler to sample all traces.
	// In a production application, use sdktrace.TraceIDRatioBased with a desired probability.
	sdktrace.WithSampler(sdktrace.AlwaysSample()),
	sdktrace.WithBatcher(exporter))

otel.SetTracerProvider(tp)

Python

Cette section illustre les modifications que vous devez apporter lorsque vous utilisez gRPC pour l'exportation. Si vous utilisez des données encodées en protobuf sur des connexions HTTP pour l'exportation, utilisez les identifiants par défaut. Vous devez également transmettre ces identifiants lorsque vous instanciez BatchSpanProcessor. Pour en savoir plus, consultez le dépôt Python.

Pour une application Python qui utilise gRPC pour l'exportation, ajoutez les importations suivantes :

import google.auth
import google.auth.transport.grpc
import google.auth.transport.requests
import grpc
from google.auth.transport.grpc import AuthMetadataPlugin

Mettez également à jour le code d'initialisation pour configurer ADC avant d'instancier l'exportateur gRPC :

credentials, _ = google.auth.default()
request = google.auth.transport.requests.Request()
resource = Resource.create(attributes={SERVICE_NAME: "otlp-gcp-grpc-sample"})

auth_metadata_plugin = AuthMetadataPlugin(credentials=credentials, request=request)
channel_creds = grpc.composite_channel_credentials(
    grpc.ssl_channel_credentials(),
    grpc.metadata_call_credentials(auth_metadata_plugin),
)

Node.js

Cette section illustre les modifications que vous devez apporter lorsque vous utilisez gRPC pour l'exportation. Si vous utilisez des données encodées en protobuf sur des connexions HTTP pour l'exportation, les modifications à apporter sont légèrement différentes de celles décrites ici. Pour en savoir plus, consultez le fichier app-http-proto-export.ts inclus dans l'application Node.js.

Pour une application Node.js qui utilise gRPC pour l'exportation, ajoutez les importations suivantes :

import {AuthClient, GoogleAuth} from 'google-auth-library';
import {credentials} from '@grpc/grpc-js';

Mettez également à jour le code d'initialisation pour configurer ADC avant d'instancier l'exportateur gRPC :

async function getAuthenticatedClient(): Promise<AuthClient> {
  const auth: GoogleAuth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/cloud-platform',
  });
  return await auth.getClient();
}

// Express App that exports traces via gRPC with protobuf
async function main() {
  const authenticatedClient: AuthClient = await getAuthenticatedClient();

  // ...
}

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"

Si vous utilisez Java et configurez votre application pour utiliser l'extension d'authentification Google Cloud, comme le fait l'exemple d'application Java, vous n'avez pas besoin de définir l'ID du projet dans les attributs de ressource OpenTelemetry. Toutefois, la définition de cet attribut n'est pas nuisible.

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

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

Si vous utilisez Java et le module de configuration automatique, vous pouvez définir le point de terminaison de l'exportateur à l'aide des propriétés système, comme le fait l'exemple d'application Java. Vous n'avez pas besoin de définir la variable d'environnement de l'exportateur pour cette configuration.

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