Instrumenter pour Cloud Trace

Vous pouvez instrumenter vos applications pour Cloud Trace afin de capturer les données de traçage distribué, examiner la latence des requêtes individuelles et afficher la latence globale de vos services dans la console Trace.

Ce document présente les approches d'instrumentation et les options de configuration. Pour obtenir des instructions détaillées pour des langages de programmation spécifiques, consultez les pages de configuration propres à chaque langage.

Quand instrumenter votre application

Lorsque les données de trace pour valider les performances ou 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 échecs. 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.

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

  • Utilisez les bibliothèques clientes Cloud Trace ou l'exportateur Cloud Trace pour OpenTelemetry.

Exemples d'instrumentation

Les exemples d'instrumentation que nous fournissons utilisent OpenTelemetry :

Créer des spans personnalisés

Bien qu'OpenTelemetry et les bibliothèques clientes vous permettent de créer des spans personnalisés, vous n'aurez peut-être pas besoin de les créer manuellement, car ces bibliothèques créent automatiquement des spans aux limites RPC.

Vous pouvez également ajouter des informations pertinentes à votre application en ajoutant des annotations et des tags personnalisés aux spans existants, ou vous pouvez créer des spans enfants avec leurs propres annotations et tags pour suivre le comportement de l'application avec une granularité plus fine.

Les bibliothèques conservent généralement un contexte de trace global qui contient des informations sur la portée actuelle, y compris son ID de trace et son état d'échantillonnage. Les applications peuvent accéder à la portée actuelle via le contexte de trace global. Étant donné que le contexte est global, assurez-vous que les applications multithread propagent le contexte sur les threads pour conserver des données de trace précises.

Forcer l'échantillonnage des traces

Vous ne pouvez pas forcer l'échantillonnage des spans, car chaque composant du chemin de requête prend une décision d'échantillonnage indépendante. Toutefois, vous pouvez influencer les composants en aval en définissant le flag sampled dans l'en-tête de trace sur true. Ce paramètre est une indication 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.

  • Vos applications : vous configurez la façon dont la logique d'instrumentation respecte l'indicateur sampled. Par exemple, lorsque vous utilisez OpenTelemetry, vous pouvez utiliser l'échantillonneur ParentBased pour vous assurer que l'indicateur d'échantillonnage du parent est respecté.

  • Google Cloud services : chaque service détermine sa propre compatibilité avec le traçage. En général, les services acceptent l'indicateur d'échantillonnage parent comme indication tout en appliquant leurs propres limites de taux d'échantillonnage.

Corréler des métriques et des traces avec des exemples

Vous pouvez corréler des données de métriques avec des traces à l'aide d'exemples. Un exemplar est un exemple de requête ou de couverture représentatif associé à une mesure de métrique. Par exemple, un exemple peut contenir un lien vers une trace, ce qui vous permet de corréler vos données de métriques et de trace. Pour obtenir un exemple basé sur OpenTelemetry, consultez Corréler des métriques et des traces à l'aide d'exemples.

Vous pouvez voir des exemples générés par le système dans les graphiques du tableau de bord qui affichent les résultats des requêtes SQL pour les données de trace. Ces exemples associent des résultats de requête spécifiques directement à des traces. Pour en savoir plus, consultez Générer et afficher des exemples de traces.

Configurer votre projet et votre plate-forme

Cette section décrit les API et les rôles IAM (Identity and Access Management) requis, et explique comment configurer les identifiants d'authentification pour votre plate-forme.

Activer les API

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

Activez les API Telemetry et Cloud Trace, si ce n'est pas déjà fait.

Rôles requis pour activer les API

Pour activer les API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation grâce au rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation grâce au rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

Activer les API

Attribuer des rôles IAM

Les rôles IAM requis dépendent de la façon dont vous affichez les données de trace (dans la console Google Cloud ou en les écrivant dans votre projet) :

  • Pour obtenir les autorisations nécessaires pour afficher les données de trace à l'aide de la console Google Cloud , demandez à votre administrateur de vous accorder le rôle IAM Utilisateur Cloud Trace (roles/cloudtrace.user) sur votre projet.

  • Pour obtenir les autorisations nécessaires pour écrire des données de trace à l'aide de l'API Cloud Trace, demandez à votre administrateur de vous accorder le rôle IAM Agent Cloud Trace (roles/cloudtrace.agent) sur votre projet.

  • Pour obtenir les autorisations nécessaires pour écrire des données de trace à l'aide de l'API Telemetry, demandez à votre administrateur de vous accorder le rôle IAM Rédacteur de données de télémétrie Cloud (roles/telemetry.writer) sur votre projet.

Authentifier

Cette section explique comment s'authentifier lorsque vos applications s'exécutent surGoogle Cloud et ailleurs.

Exécuter sur Google Cloud

Lorsque votre application s'exécute sur Google Cloud, vous n'avez généralement pas besoin de fournir d'identifiants d'authentification. Toutefois, certaines bibliothèques clientes de langage nécessitent l'ID du projet, même lorsqu'elles sont hébergées sur Google Cloud.

Vérifiez que le niveau d'accès à l'API Cloud Trace est activé pour 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 :

Si vous utilisez des niveaux d'accès personnalisés, vous devez vous assurer que le niveau d'accès à 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écuter en local et depuis un autre emplacement

Si votre application s'exécute en dehors de Google Cloud, vous devez fournir des identifiants d'authentification à la bibliothèque cliente. Le compte de service doit disposer du rôle Agent Cloud Trace (roles/cloudtrace.agent). Pour en savoir plus sur les rôles, consultez Contrôler l'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 fichier de clé du compte de service dans un chemin d'accès par défaut pour votre système d'exploitation. Vous trouverez ci-dessous les 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