Présentation de Cloud Trace

Cloud Trace, un système de traçage distribué pourGoogle Cloud, vous aide à comprendre le temps nécessaire à votre application pour gérer les requêtes entrantes des utilisateurs ou d'autres applications, ainsi que le temps nécessaire pour effectuer des opérations telles que les appels RPC. Trace peut également vous aider lorsque vous développez un service ou une application agentique, ou lorsque vous résolvez un problème. Par exemple, il peut vous aider à comprendre comment les requêtes sont traitées dans une architecture de microservices complexe et à identifier les journaux à examiner.

Comme Trace reçoit des données de latence des services Google Cloud , comme App Engine, et des applications que vous instrumentez, il peut vous aider à répondre aux questions suivantes :

  • Combien de temps faut-il à mon application pour traiter une requête donnée ?
  • Pourquoi mon application est-elle si longue à traiter ma requête ?
  • Pourquoi le traitement de certaines requêtes est-il plus long que pour d'autres ?
  • Quelle est la latence globale des requêtes adressées à mon application ?
  • La latence de mon application a-t-elle augmenté ou diminué avec le temps ?
  • Que puis-je faire pour réduire la latence de mon application ?
  • Quelles sont les dépendances de mon application ?

Si vous souhaitez savoir comment utiliser Trace pour gérer vos applications, consultez le blog Dépannage des applications distribuées : utiliser conjointement les traces et les journaux pour analyser l'origine des problèmes.

Pour en savoir plus sur le profilage de votre application, consultez Cloud Profiler.

Environnements compatibles

Trace s'exécute sous Linux dans les environnements suivants :

Trace fournit des bibliothèques clientes pour instrumenter votre application afin de capturer des informations de trace. Pour obtenir les instructions de configuration par langage, consultez Instrumenter pour Trace.

Configurations avec traçage automatique

Certaines configurations entraînent la capture automatique des données de trace :

  • Environnement standard App Engine

    Les applications Java 8, Python 2 et PHP 5 n'ont pas besoin d'utiliser les bibliothèques clientes Trace. Ces environnements d'exécution envoient automatiquement des données de latence à Trace pour les requêtes adressées aux URI de l'application. Les requêtes incluent des données de latence pour les appels RPC aller-retour aux services App Engine. Trace fonctionne avec toutes les API d'administration d'App Engine, à l'exception de Cloud SQL.

  • Cloud Run Functions et Cloud Run

    Pour les requêtes HTTP entrantes et sortantes, les données de latence sont automatiquement envoyées à Trace.

API qui ingèrent les données de trace

Vous pouvez envoyer des données de trace à votre projet à l'aide de l'API Telemetry ou de l'API Cloud Trace. Nous vous recommandons d'utiliser l'API Telemetry pour les raisons suivantes :

  • L'API est compatible avec l'écosystème Open Source OpenTelemetry et ses limites sont souvent plus généreuses que celles de l'API Cloud Trace, qui est une API propriétaire Google Cloud .

  • Vos données de trace sont stockées dans un format généralement compatible avec les fichiers proto définis par le protocole de ligne OpenTelemetry. Avant d'être stockés, certains champs peuvent être convertis d'un type de données spécifique à OpenTelemetry en type de données JSON. Pour en savoir plus sur le format de stockage, consultez Schéma des données de trace.

  • Pour l'exportation des données de trace basée sur un collecteur, votre instrumentation ne repose pas sur un exportateur spécifique à Google Cloud.

  • Certaines fonctionnalités, comme la surveillance des applications, s'appuient sur des informations qui ne sont disponibles que lorsque vous envoyez des données de trace à l'API Telemetry.

Si vous souhaitez empêcher votre projet Google Cloud de stocker des données de trace, désactivez l'API Cloud Trace. La désactivation de l'API Cloud Trace entraîne les conséquences suivantes :

  • Les servicesGoogle Cloud n'envoient pas de données de trace à votre projet.
  • Google Cloud répond aux requêtes envoyées à un point de terminaison de l'API Cloud Trace avec un code d'erreur.
  • Google Cloud Observability supprime les données de trace envoyées au point de terminaison de l'API Telemetry spécifique aux traces. Ne désactivez pas l'API Telemetry, car elle peut recevoir des données de journaux, de métriques et de trace.

Si vous gérez une organisation et que vous souhaitez empêcher l'utilisation de Cloud Trace, créez une contrainte de règle d'administration.

Cloud Trace et applications agentiques

Pour comprendre le comportement de vos applications agentiques, configurez-les pour qu'elles collectent les prompts et les réponses, ou pour qu'elles génèrent des segments lorsqu'elles appellent des serveurs MCP Google Cloud à distance. Les requêtes et les réponses vous aident à comprendre le raisonnement utilisé par votre application agentique. Les spans qui enregistrent les appels d'outils vous aident à confirmer l'invocation d'outils, les états des appels et les latences des requêtes.

Plusieurs exemples d'instrumentation vous montrent comment configurer une application pour collecter les requêtes et les réponses. Ces exemples reposent sur OpenTelemetry. Pour en savoir plus, 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 segments, consultez Examiner les appels MCP à l'aide de Trace.

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

Les exemples d'instrumentation que nous fournissons utilisent OpenTelemetry :

  • 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 segments, consultez Examiner les appels MCP à l'aide de Trace.

Vous pouvez également utiliser les bibliothèques clientes Cloud Trace pour instrumenter votre application. Toutefois, nous vous recommandons d'utiliser OpenTelemetry. Les bibliothèques OpenTelemetry sont préférables aux bibliothèques clientes Trace, car elles sont plus simples et exportent les données de trace au format OTLP, défini par OpenTelemetry. Pour en savoir plus, consultez Bibliothèques clientes pour Cloud Trace.

Composants

Trace est un client de traçage qui collecte des traces et les envoie à votre projet Google Cloud . Vous pouvez ensuite utiliser la consoleGoogle Cloud pour afficher et analyser les données collectées par l'agent. Pour en savoir plus sur le modèle de données, consultez Traces et spans.

Client de traçage

Si une bibliothèque OpenTelemetry est disponible pour votre langage de programmation, vous pouvez simplifier le processus de création et d'envoi de données de trace en utilisant OpenTelemetry. En plus d'être plus simple à utiliser, OpenTelemetry met en œuvre le traitement par lots, ce qui peut améliorer les performances.

Si aucune bibliothèque OpenTelemetry n'est disponible, instrumentez votre code en important la bibliothèque du SDK Trace et en utilisant l'API Cloud Trace. L'API Cloud Trace envoie les données de trace à votre projet Google Cloud .

Interface de traçage

Vous pouvez afficher et analyser vos données de trace en temps quasi réel dans l'interface Trace.

Pour afficher et analyser vos données de segment, vous pouvez utiliser les pages Explorateur de traces et Analytics d'observabilité de la consoleGoogle Cloud  :

  • Explorateur Trace : affiche des informations globales sur vos données de trace et vous permet d'examiner des traces individuelles en détail. Les données de latence agrégées sont affichées sur une carte de densité que vous pouvez explorer avec votre pointeur. Pour limiter les données affichées, vous pouvez ajouter des filtres. Cette page vous permet également d'afficher et d'explorer des portées et des traces individuelles :

  • Observability Analytics : cette page vous permet d'exécuter des requêtes qui effectuent une analyse agrégée de vos spans à l'aide de SQL. Vos requêtes SQL peuvent également joindre vos données de trace et de journal. Vous pouvez afficher les résultats de votre requête sous forme de tableau ou de graphiques. Si vous créez un ensemble de données associé, vous pouvez utiliser BigQuery pour analyser vos spans. Pour en savoir plus, consultez Interroger et analyser des traces.

Compatibilité avec VPC Service Controls

Trace est un service compatible avec VPC Service Controls. Le nom du service de trace est cloudtrace.googleapis.com. Toutes les restrictions VPC Service Controls que vous créez pour le service Trace ne s'appliquent qu'à ce service. Ces restrictions ne s'appliquent à aucun autre service, y compris ceux comme le telemetry.googleapis.com, qui peuvent également ingérer des données de trace.

Pour en savoir plus, consultez les ressources suivantes :

Cloud Trace et résidence des données

Si vous utilisez Assured Workloads parce que vous avez des exigences de résidence des données ou de niveau d'impact 4 (IL4), n'utilisez pas l'API Cloud Trace pour envoyer des spans de trace.

Si vous souhaitez empêcher votre projet Google Cloud de stocker des données de trace, désactivez l'API Cloud Trace. La désactivation de l'API Cloud Trace entraîne les conséquences suivantes :

  • Les servicesGoogle Cloud n'envoient pas de données de trace à votre projet.
  • Google Cloud répond aux requêtes envoyées à un point de terminaison de l'API Cloud Trace avec un code d'erreur.
  • Google Cloud Observability supprime les données de trace envoyées au point de terminaison de l'API Telemetry spécifique aux traces. Ne désactivez pas l'API Telemetry, car elle peut recevoir des données de journaux, de métriques et de trace.

Si vous gérez une organisation et que vous souhaitez empêcher l'utilisation de Cloud Trace, créez une contrainte de règle d'administration.

Tarifs

Pour en savoir plus sur les tarifs de Cloud Trace, consultez la page Tarifs de Google Cloud Observability.

Étapes suivantes