Java et OpenTelementry

Cette page est conçue pour les développeurs d'applications qui souhaitent collecter des données Cloud Trace pour les applications Java à l'aide d'OpenTelemetry. OpenTelemetry est un ensemble de bibliothèques d'instrumentation permettant de collecter des données de trace et de métrique. Ces bibliothèques fonctionnent avec plusieurs backends. Pour collecter des traces avec OpenTelementry et Java, vous devez suivre la procédure ci-dessous:

  • Installer les packages OpenTelemetry
  • Configurez votre application pour exporter les délais vers Cloud Trace.
  • Configurez votre plate-forme.

Pour obtenir des informations sur la version, consultez les articles suivants:

Pour obtenir les dernières informations sur OpenTelemetry pour Java, ainsi que de la documentation et des exemples supplémentaires, consultez la page OpenTelemetry.

Avant de commencer

  • Vous devez utiliser Java 8 ou une version ultérieure.
  • Vérifiez que l'API Cloud Trace est activée pour votre projet Google Cloud:

    1. Cliquez sur le bouton suivant ou, dans Google Cloud Console, sélectionnez API et services, puis API Cloud Trace:

      Accéder à l'API Trace

    2. Sur la page API Cloud Trace, si un bouton intitulé Activer s'affiche, cliquez dessus. Si ce bouton ne s'affiche pas, l'API Cloud Trace est activée pour le projet sélectionné.

Installer les packages OpenTelementry

Pour collecter les traces, ajoutez le traçage OpenTelemetry et l'exportateur Cloud Trace pour OpenTelemetry au fichier Maven ou Gradle de votre application:

  • Pour obtenir la liste la plus récente des dépendances OpenTelemetry, consultez les pages Maven et Gradle.

  • Pour connaître les dépendances requises de l'exportateur, consultez le tableau suivant:

    Maven

    <dependency>
      <groupId>com.google.cloud.opentelemetry</groupId>
      <artifactId>exporter-trace</artifactId>
      <version>0.15.0</version>
    </dependency>
    

    Les instructions précédentes spécifient une version d'exportateur. Veillez à sélectionner la dernière version de l'exportateur.

    Gradle

    implementation 'com.google.cloud.opentelemetry:exporter-trace:0.15.0'
    

    L'instruction précédente spécifie une version d'exportateur. Veillez à sélectionner la dernière version de l'exportateur.

Configurer l'exportation des délais vers Cloud Trace

Pour exporter les données Trace collectées, utilisez un objet TraceExporter. L'exemple suivant montre comment créer cet objet avec une configuration par défaut:

TraceExporter traceExporter = TraceExporter.createWithDefaultConfiguration();

Vous pouvez également spécifier une configuration, puis la transmettre à l'exportateur. Par exemple, le code suivant définit le projet Google Cloud:

TraceExporter traceExporter = TraceExporter.createWithConfiguration(
  TraceConfiguration.builder().setProjectId("MY_PROJECT").build());

Une fois l'exportateur configuré, définissez le paramètre TracerProvider:

OpenTelemetrySdk.builder()
          .setTracerProvider(
              SdkTracerProvider.builder()
                  .addSpanProcessor(BatchSpanProcessor.builder(traceExporter).build())
                  .build())
          .buildAndRegisterGlobal();

Dans l'exemple précédent, l'appel à BatchSpanProcessor configure le fournisseur pour qu'il envoie des délais à un processus en arrière-plan. Nous vous recommandons d'utiliser cette configuration, sauf si vous utilisez Cloud Run. Cloud Run n'est pas compatible avec les processus en arrière-plan.

Pour plus d'informations sur la définition des champs d'authentification, consultez la section de configuration de l'exportateur Cloud Trace pour OpenTelemetry.

Créer des délais

Pour savoir comment configurer votre application pour capturer des délais de trace, consultez la page Traçage OpenTelemetry. Cette page explique comment effectuer toutes les opérations suivantes:

  • Créer un délai
  • Créer des délais imbriqués
  • Définir les attributs de délai
  • Créer des délais avec des événements
  • Créer des délais avec des liens

Configurer l'échantillonnage

Pour plus d'informations sur la configuration de l'échantillonnage des traces, consultez la section Échantillonneur OpenTelemetry. Cette page décrit les options d'échantillonnage disponibles.

Exemple d'application

Pour obtenir un exemple d'application, consultez TraceExporterExample.java.

Configurer votre plate-forme

Vous pouvez utiliser Cloud Trace sur Google Cloud et d'autres plates-formes.

Exécuter des applications sur Google Cloud

Lorsque votre application s'exécute sur Google Cloud, vous n'avez pas besoin de fournir des identifiants d'authentification sous la forme d'un compte de service à la bibliothèque cliente. Cependant, vous devez vous assurer que le niveau d'accès de l'API Cloud Trace est activé sur votre plate-forme Google Cloud.

Pour obtenir la liste des environnements Google Cloud compatibles, consultez la page Environnements compatibles.

Pour les configurations suivantes, les paramètres de niveau d'accès par défaut activent l'API Cloud Trace :

  • Environnement flexible App Engine
  • Environnement standard App Engine

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

Si vous utilisez des champs d'application d'accès personnalisés, vous devez vous assurer que le niveau d'accès à l'API Cloud Trace est activé:

  • Pour savoir comment configurer les niveaux d'accès pour votre environnement à l'aide de Google Cloud Console, consultez la page Configurer votre projet Google Cloud.

  • Pour les utilisateurs gcloud, spécifiez les niveaux d'accès à l'aide de l'option --scopes et incluez les champs d'application d'accès à l'API Cloud Trace trace.append. Par exemple, pour créer un cluster GKE avec uniquement l'API Cloud Trace activée, procédez comme suit :

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

Exécuter en local et depuis un autre emplacement

Si votre application s'exécute en dehors de Google Cloud, vous devez fournir les identifiants d'authentification sous la forme d'un compte de service à la bibliothèque cliente. Le compte de service doit contenir le rôle d'agent Cloud Trace. Pour savoir comment faire, consultez la page Créer un compte de service.

Les bibliothèques clientes Google Cloud utilisent les identifiants par défaut de l'application (ADC) pour trouver les identifiants de votre application. Vous fournissez ces identifiants en définissant la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS :

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Powershell :

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

Afficher les traces

Après le déploiement, vous pouvez afficher les traces dans la visionneuse de traces de Cloud Console.

Accéder à la page Lecteur de traces

Dépannage

Pour en savoir plus sur la résolution des problèmes liés à Cloud Trace, consultez la page Dépannage.

Resources