Instrumenter pour Cloud Trace

Vous pouvez instrumenter vos applications pour Cloud Trace afin de capturer des 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 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 aideront à comprendre ses performances et à résoudre les échecs. Plusieurs frameworks d'instrumentation Open Source collectent des données de journal, de métrique et de trace données, 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 un contexte qui permet de suivre 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 du vue du fournisseur, tel qu' OpenTelemetry, plutôt que des API spécifiques aux fournisseurs et aux produits ou des bibliothèques clientes. Pour en savoir plus sur ces frameworks, consultez Instrumentation et observabilité et Choisir une approche d'instrumentation.

Comment instrumenter des applications

Vous pouvez utiliser plusieurs approches pour instrumenter votre application :

  • Recommandé : Utilisez OpenTelemetry, configurez votre application avec un exportateur OTLP qui envoie des données de trace à un collecteur, puis configurez le collecteur pour qu'il envoie des données de trace à votre Google Cloud projet à 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 Google Cloud projet à 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 for 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 segments personnalisés

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

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

Les bibliothèques gèrent généralement un contexte de trace global contenant des informations sur le segment actuel, y compris son ID de trace et son état d'échantillonnage. Les applications peuvent accéder au segment actuel via le contexte de trace global. Comme le contexte est global, assurez-vous que les applications multithread propagent le contexte entre les threads pour conserver des données de trace précises.

Forcer l'échantillonnage des traces

Vous ne pouvez pas forcer l'échantillonnage des segments, 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 l' sampled indicateur dans l'en-tête de trace sur true. Ce paramètre est une indication pour les composants enfants 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 manière 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étrique avec des traces à l'aide d'exemples. Un exemple est une requête ou un segment d'échantillon 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étrique 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 directement des résultats de requête spécifiques à des traces. Pour en savoir plus, consultez Générer et afficher des exemples de trace.

Configurer votre projet et votre plate-forme

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

Activer les API

Par défaut, Google Cloud l'API Cloud Trace et l'API Telemetry sont activées pour les projets, 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'une de ces API ou les deux. 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.

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 via le rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation via le rôle Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

Activer les API

Accorder des rôles IAM

Les rôles IAM requis dépendent du fait que vous affichiez des données de trace dans la Google Cloud console ou que vous écriviez des données de trace dans votre projet :

  • Pour obtenir les autorisations nécessaires pour afficher les données de trace à l'aide de la Google Cloud console, 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 télémétrie Cloud (roles/telemetry.writer) sur votre projet.

Authentifier

Cette section explique comment s'authentifier lorsque vos applications s'exécutent sur Google Cloud et lorsqu'elles s'exécutent 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 de l'API Cloud Trace est activé sur votre Google Cloud plate-forme. Pour les configurations suivantes, les paramètres de niveau d'accès par défaut incluent le niveau d'accès de l'API Cloud Trace :

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

Google Cloud Les bibliothèques clientes 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écutez gcloud auth application-default login.

  • Placez le fichier de clé de 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"

Étape suivante