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 framework d'instrumentation neutre du fournisseur que vous pouvez utiliser pour collecter des données de trace et de métriques. Pour en savoir plus sur l'instrumentation de votre code, consultez la page Instrumentation et observabilité.
- Installez les packages OpenTelementry.
- Configurez votre application pour exporter les délais vers Cloud Trace.
- Configurez votre plate-forme.
Pour en savoir plus sur les versions, consultez les articles suivants :
Pour accéder au contenu de référence d'OpenTelemetry, consultez les pages suivantes:
Pour obtenir les dernières informations sur OpenTelemetry pour Java, ainsi que de la documentation supplémentaire et des exemples, consultez la section OpenTelemetry.
Avant de commencer
- Vous devez utiliser Java 8 ou une version ultérieure.
-
Dans le panneau de navigation de la console Google Cloud, sélectionnez API et services, cliquez sur Activer les API et les services, puis activez l'API Cloud Trace:
Si API activée s'affiche, l'API est déjà activée. Sinon, cliquez sur le bouton Activer.
Installer les packages OpenTelementry
Pour collecter des traces, ajoutez le traçage OpenTelemetry et l'exportateur Cloud Trace pour OpenTelementry 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 d'exportateur requises, 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 version la plus récente 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 version la plus récente 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 champ 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 segments avec un processus en arrière-plan.
Pour en savoir plus sur la définition des champs d'authentification, consultez la section sur la configuration de l'exportateur Cloud Trace pour OpenTelemetry.
Créer des délais
Pour en savoir plus sur la configuration de votre application pour capturer des délais de trace, consultez la page Traçage OpenTelemetry. Cette page explique comment effectuer les opérations suivantes :
- Créer un délai
- Créer des délais imbriqués
- Définir des 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 en savoir plus sur la configuration de l'échantillonnage des traces, consultez la page Échantillonneur OpenTelemetry. Cette page décrit les options d'échantillonnage disponibles.
Exemple d'application
Pour obtenir un exemple d'application, consultez la section 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 niveaux d'accès personnalisés, assurez-vous que le niveau d'accès de l'API Cloud Trace est activé :
Pour en savoir plus sur la configuration des niveaux d'accès pour votre environnement à l'aide de la console Google Cloud, consultez la page Configurer votre projet Google Cloud.
Pour les utilisateurs
gcloud
, spécifiez les niveaux d'accès à l'aide de l'indicateur--scopes
et incluez le niveau d'accès à l'API Cloud Tracetrace.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 pouvez fournir ces identifiants de l'une des trois manières suivantes:
Exécuter
gcloud auth application-default login
Placez le compte de service dans un chemin d'accès par défaut pour votre système d'exploitation. Voici la liste des chemins d'accès par défaut pour Windows et Linux:
Windows :
%APPDATA%/gcloud/application_default_credentials.json
Linux :
$HOME/.config/gcloud/application_default_credentials.json
Définissez la variable d'environnement
GOOGLE_APPLICATION_CREDENTIALS
pour qu'elle indique le chemin d'accès à votre compte de service:
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
Dans le panneau de navigation de la console Google Cloud, sélectionnez Trace, puis Explorateur Trace:
Dépannage
Pour en savoir plus sur la résolution des problèmes liés à Cloud Trace, consultez la page Dépannage.
Ressources
- https://opentelemetry.io/
- Dépôt GitHub OpenTelemetry/opentelemetry-java
- Dépôt GitHub Google Cloud opentelemetry-operations-java.