Instrument 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 ne sont pas capturées automatiquement, vous devez instrumenter votre application pour les collecter.

Vous pouvez instrumenter votre application de sorte qu'elle collecte des informations spécifiques. Plusieurs frameworks d'instrumentation Open Source vous permettent de collecter des métriques, des journaux et des traces à partir de votre application, et d'envoyer ces données à n'importe quel fournisseur, y compris Google Cloud. 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 l'instrumentation de vos applications à l'aide de frameworks d'instrumentation neutres concernant les fournisseurs, consultez la page Instrumentation et observabilité.

Comment instrumenter les applications

Pour obtenir des recommandations sur l'instrumentation de vos applications pour collecter des journaux, des métriques et des traces, consultez la page Choisir une approche d'instrumentation.

Pour instrumenter vos applications afin de collecter des données de trace, vous pouvez effectuer l'une des opérations suivantes:

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

Lorsque vous exécutez une application sur Google Cloud, vous n'avez généralement pas besoin de fournir d'identifiants d'authentification à votre application ni de spécifier l'ID de votre projet Google Cloud dans votre application. 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 Workload Identity, vous devez configurer votre application pour qu'elle utilise Workload Identity.

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 projet Google 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 pas tous les segments, 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 à l'en-tête de trace une option sampled, avec cette option définie sur true. Ce paramètre donne aux composants enfants une indication pour échantillonner la requête. Pour en savoir plus sur les en-têtes de trace, consultez la page Protocoles pour la propagation du contexte.

Pour les composants en aval dont vous êtes propriétaire du 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 vous servir de l'échantillonneur ParentBased pour vous assurer que l'indicateur d'échantillon parent est respecté.

Les services Google Cloud qui enregistrent les informations de traçage dans Cloud Trace acceptent généralement l'option d'échantillonnage parent à titre d'indication. Toutefois, la plupart des services limitent également l'échantillonnage. Chaque service Google Cloud détermine s'il accepte le traçage, le mode d'utilisation de l'indicateur d'échantillonnage parent et le débit maximal d'échantillonnage.

Activer l'API Cloud Trace

Pour utiliser Cloud Trace, l'API Cloud Trace doit être activée pour votre projet Google Cloud. Ce paramètre permet à votre projet Google Cloud de recevoir des données de trace provenant de sources authentifiées. 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, vous devrez peut-être activer l'API Cloud Trace si vous avez modifié les niveaux d'accès de votre projet Google Cloud.

Pour activer l'API Cloud Trace, procédez comme suit:

  1. 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:

    Accéder aux paramètres de l'API Cloud Trace

  2. Si API activée s'affiche, l'API est déjà activée. Sinon, cliquez sur le bouton Activer.

É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 :