Instrumenter pour Cloud Trace

Ce document fournit une brève présentation sur la manière d'instrumenter votre application pour Cloud Trace. Pour obtenir des instructions détaillées sur la configuration de Cloud Trace, consultez les pages de configuration spécifiques à chaque langage.

Cloud Trace fournit des données de traçage distribuées pour vos applications. Après avoir instrumenté votre application, vous pouvez inspecter les données de latence d'une seule requête et afficher la latence globale d'une application entière dans la console Cloud Trace.

Quand instrumenter votre application

Lorsque les données de trace permettant de valider les performances ou de résoudre les problèmes ne sont pas capturées automatiquement, instrumentez votre application.

Instrumentez votre application pour collecter des informations spécifiques qui vous aident à comprendre ses performances et à résoudre les problèmes. Plusieurs frameworks d'instrumentation Open Source collectent des données de journaux, de métriques et de traces, et peuvent envoyer ces données à n'importe quel fournisseur, y compris Google Cloud. Pour vos applications agentiques, certains frameworks peuvent collecter vos requêtes et vos réponses, ou transmettre le contexte qui permet de tracer certains appels de serveurs MCP Google Cloud à distance.

Pour instrumenter votre application, nous vous recommandons d'utiliser un framework d'instrumentation Open Source neutre du point de vue du fournisseur, tel qu'OpenTelemetry, plutôt que des API ou des bibliothèques clientes spécifiques aux fournisseurs et aux produits. Pour en savoir plus sur ces frameworks, consultez Instrumentation et observabilité et Choisir une approche d'instrumentation.

Instrumenter des applications

Vous pouvez instrumenter votre application de plusieurs façons :

Recommandé : utilisez OpenTelemetry, configurez votre application avec un exportateur OTLP qui envoie les données de trace à un collecteur, puis configurez le collecteur pour qu'il envoie les données de trace à votre projet Google Cloud à l'aide de l'API Telemetry (OTLP). Pour en savoir plus sur nos recommandations, consultez Choisir une approche d'instrumentation.
Utilisez OpenTelemetry et configurez votre application avec un exportateur OTLP qui envoie vos données de trace à votre projet Google Cloud à l'aide de l'API Telemetry.
Si vous écrivez des applications qui s'exécutent sur Compute Engine, vous pouvez utiliser l'agent Ops et le récepteur OTLP (OpenTelemetry Protocol) pour collecter des traces et des métriques à partir de votre application. L'agent Ops peut également collecter des journaux, mais pas à l'aide d'OTLP. Pour en savoir plus, consultez Utiliser l'agent Ops et OTLP et Présentation de l'agent Ops.
Appelez directement l'API Telemetry ou l'API Cloud Trace.
Utilisez les bibliothèques clientes Cloud Trace ou l'exportateur Cloud Trace pour OpenTelemetry.
Pour les applications Spring Boot, configurez-les pour qu'elles transfèrent les données de trace qu'elles collectent vers Cloud Trace. Pour en savoir plus sur cette procédure, consultez Spring Cloud pour Google Cloud : Cloud Trace.

Les exemples d'instrumentation que nous fournissons utilisent OpenTelemetry :

Pour les exemples qui utilisent une exportation basée sur un collecteur, consultez les éléments suivants :
- Go
- Java
- Node.js
- Python
Ces exemples envoient des données de trace à l'API Telemetry.
Pour savoir comment utiliser l'exportation directe des données de trace et les envoyer à l'API Telemetry, consultez Migrer de l'exportateur Trace vers le point de terminaison OTLP.
Pour obtenir des exemples montrant comment configurer une application agentique pour collecter des requêtes et des réponses, consultez Instrumenter vos applications d'IA générative.
Pour savoir quels serveurs MCP Google Cloud distants sont compatibles avec la génération de traces et comment configurer votre application pour demander à ces serveurs de créer des spans, consultez Examiner les appels MCP à l'aide de Trace.

Quand créer des délais

Les bibliothèques clientes Cloud Trace gèrent généralement un contexte de trace global contenant des informations sur le délai actuel, y compris son ID de trace et si la trace est échantillonnée. Ces bibliothèques créent généralement des délais sur les limites RPC. Cependant, vous devrez peut-être créer des délais si l'algorithme de création par défaut n'est pas suffisant pour vos besoins.

Le délai actif actuel est accessible par le contexte de trace global, parfois encapsulé dans un objet Traceur. Vous pouvez ajouter des informations pertinentes à votre application en utilisant des annotations et des tags personnalisés pour les délais existants, ou créer des délais enfants avec leurs propres annotations et tags pour suivre le comportement de l'application avec une plus grande précision. Comme le contexte est global, les applications multithread qui mettent à jour le contexte doivent utiliser l'isolation appropriée.

Quand fournir des identifiants d'authentification

En général, vous n'avez pas besoin de fournir des identifiants d'authentification à votre application ni de spécifier votre ID de projet Google Cloud dans votre application lorsque vous exécutez sur Google Cloud. Pour certains langages, vous devez spécifier votre ID de projet Google Cloud même si vous exécutez sur Google Cloud. De plus, si vous utilisez le mode Autopilot pour Google Kubernetes Engine ou si vous activez la fédération d'identité de charge de travail pour GKE, vous devez configurer votre application pour qu'elle utilise la fédération d'identité de charge de travail pour GKE.

Si vous exécutez en dehors de Google Cloud, vous devez fournir des identifiants d'authentification à votre application. Vous devez également spécifier votre ID de projetGoogle Cloud dans votre application.

Pour en savoir plus, consultez les pages de configuration propres à chaque langue.

Forcer le traçage d'une requête

À moins que votre application n'échantillonne toujours chaque span, il n'est généralement pas possible de forcer le traçage de bout en bout d'une requête, car chaque composant d'une requête de bout en bout prend sa propre décision d'échantillonnage. Toutefois, vous pouvez influencer la décision en ajoutant un indicateur sampled à l'en-tête de trace, en définissant cet indicateur sur true. Ce paramètre est un indice pour les composants enfants afin d'échantillonner la requête. Pour en savoir plus sur les en-têtes de trace, consultez Protocoles de propagation du contexte.

Pour les composants en aval dont vous possédez le code, vous devez déterminer si votre logique d'instrumentation respecte l'indicateur sampled. Par exemple, lorsque vous utilisez OpenTelemetry pour l'instrumentation, vous pouvez utiliser l'échantillonneur ParentBased pour vous assurer que l'indicateur d'échantillonnage parent est respecté.

Les servicesGoogle Cloud qui enregistrent des informations de traçage dans Cloud Trace acceptent généralement l'indicateur d'échantillonnage parent comme indication. Toutefois, la plupart des services limitent également l'échantillonnage en fonction du débit. Chaque Google Cloud service détermine s'il prend en charge le traçage, comment l'indicateur d'échantillonnage parent est utilisé et la limite de fréquence d'échantillonnage.

Corréler des données de métriques et de trace

Vous pouvez corréler les données de métriques à valeurs de distribution avec les traces en associant des exemples aux points de données de métriques. Si vous effectuez les étapes de configuration nécessaires, OpenTelemetry, qui est la bibliothèque d'instrumentation recommandée, ajoute automatiquement ces exemples. Pour en savoir plus, consultez Corréler des métriques et des traces à l'aide d'exemples.

Configurer votre projet et votre plate-forme

Assurez-vous que l'API Cloud Trace est activée.

Par défaut,l'API Cloud Trace est activée pour les projets Google Cloud et aucune action n'est requise de votre part. Toutefois, les contraintes de sécurité définies par votre organisation peuvent avoir désactivé l'API. Pour en savoir plus sur la résolution des problèmes, consultez Développer des applications dans un environnement Google Cloud limité.

Activez l'API Cloud Trace.
Rôles requis pour activer les API
Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.
Activer l'API
Configurez votre plate-forme.

Vous pouvez utiliser Cloud Trace sur Google Cloud et d'autres plates-formes.
- Google Cloud : lorsque votre application s'exécute surGoogle 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 les configurations suivantes, les paramètres de niveau d'accès par défaut incluent le niveau d'accès l'API Cloud Trace :
  - Compute Engine
  - Google Kubernetes Engine (GKE)
    
    Remarque : Si vous utilisez Autopilot ou si vous activez la fédération d'identité de charge de travail pour GKE pour votre cluster GKE, assurez-vous de configurer votre application pour qu'elle utilise la fédération d'identité de charge de travail pour GKE.
  - Environnement flexible App Engine
  - Environnement standard App 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é. Par exemple, si vous utilisez Google Cloud CLI pour créer un cluster GKE et que vous spécifiez l'option --scopes, assurez-vous que le champ d'application inclut trace.append. La commande suivante illustre la définition de l'option --scopes :
```
gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append
```
- Exécution en local et ailleurs : si votre application s'exécute en dehors deGoogle Cloud, vous devez fournir des identifiants d'authentification sous la forme d'un compte de service à la bibliothèque cliente. Le compte de service doit disposer du rôle d'agent Cloud Trace (roles/cloudtrace.agent). Pour en savoir plus sur les rôles, consultez Contrôler les accès avec IAM.
  
  Les bibliothèques clientesGoogle Cloud utilisent les identifiants par défaut de l'application (ADC) pour trouver les identifiants de votre application. Vous pouvez fournir ces identifiants de trois manières :
  - 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. Vous trouverez ci-dessous 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 sur 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"

Étapes suivantes

Pour obtenir des informations détaillées sur la configuration, des exemples et des liens vers GitHub et d'autres dépôts Open Source, accédez à la page de configuration de votre langage.

Exemples OpenTelemetry :