Présentation de Cloud Trace

Cloud Trace est un système de traçage distribué pour Google Cloud qui suit la latence des requêtes et vous aide à résoudre les goulots d'étranglement des performances entre les services et les applications d'IA générative. En collectant les données de latence des Google Cloud services et des applications instrumentées, Trace vous aide à comprendre comment les requêtes sont traitées dans une architecture de microservices et à identifier les journaux pertinents.

Trace vous aide à répondre à des questions telles que les suivantes :

  • Combien de temps faut-il à votre application pour traiter une requête donnée ?
  • Pourquoi une requête met-elle autant de temps à se terminer ?
  • Pourquoi certaines requêtes sont-elles plus longues que d'autres ?
  • Quelle est la latence globale des requêtes adressées à votre application ?
  • La latence de l'application a-t-elle augmenté ou diminué au fil du temps ?
  • Comment réduire la latence de l'application ?
  • Quelles sont les dépendances de votre application ?

Pour savoir comment utiliser conjointement les traces et les journaux pour analyser l'origine des problèmes, consultez l'article de blog Résoudre les problèmes liés aux 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 sur Linux dans les environnements suivants :

Composants

Trace comprend un client de traçage, qui collecte des traces et les envoie à votre Google Cloud projet. Vous pouvez ensuite utiliser la Google Cloud console pour consulter et analyser les données collectées par le client de traçage. Pour en savoir plus sur le modèle de données, consultez Traces et segments.

Client de traçage

Un client de traçage collecte les données de latence et de segment de votre application, puis les exporte vers votre Google Cloud projet. En fonction de votre environnement et de vos exigences, vous pouvez collecter des données de trace automatiquement ou manuellement en instrumentant le code de votre application.

Interface de traçage

Pour afficher et analyser vos données de segment, vous pouvez utiliser les Explorateur Trace et Observability Analytics pages de la Google Cloud console :

  • Explorateur Trace : affiche des informations agrégées 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. Vous pouvez également afficher et explorer des segments et des traces individuels :

  • Observability Analytics : fournit une interface de requête SQL. Vos requêtes peuvent joindre vos données de trace et de journal, et vous pouvez afficher les résultats de la requête sous forme de tableau ou de graphique. Vous pouvez utiliser BigQuery pour analyser vos données de trace si vous créez un ensemble de données BigQuery associé. Pour en savoir plus, consultez Interroger et analyser des traces.

Configurations avec traçage automatique

Les configurations suivantes capturent automatiquement les données de trace :

  • Environnement standard App Engine

  • Fonctions Cloud Run et Cloud Run

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

Instrumenter votre application

Instrumentez votre application pour collecter des informations spécifiques qui vous aideront à comprendre ses performances et à résoudre les problèmes. 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 de 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.

Les exemples d'instrumentation que nous fournissons utilisent OpenTelemetry :

Bien que vous puissiez utiliser des bibliothèques clientes Cloud Trace pour instrumenter votre application, 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 Instrumenter pour Trace et Bibliothèques clientes pour Cloud Trace.

Cloud Trace et applications agentiques

Pour comprendre le comportement de vos applications agentiques, configurez-les pour qu'elles collectent des requêtes et des 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 segments qui enregistrent les appels d'outils vous aident à confirmer l'appel d'outils, les états d'appel et les latences des requêtes.

Plusieurs exemples d'instrumentation vous montrent comment configurer une application pour collecter des requêtes et des réponses. Ces exemples s'appuient sur OpenTelemetry. Pour en savoir plus, consultez Instrumenter vos applications d'IA générative.

Les serveurs MCP Google Cloud peuvent générer des segments de trace. Pour en savoir plus, consultez Examiner les appels MCP à l'aide de Trace.

API qui ingèrent des 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 uneAPI propriétaire. Google Cloud

  • Vos données de trace sont stockées dans un format généralement cohérent avec les fichiers proto définis par OTLP. Certains champs peuvent être convertis d'un type de données spécifique à OpenTelemetry en un type de données JSON avant le stockage. 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 dépend pas d'un Google Cloud-exportateur spécifique.

  • Certaines fonctionnalités, telles que 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.

Pour empêcher votre Google Cloud projet de stocker des données de trace, désactivez l' API Cloud Trace. La désactivation de l'API Cloud Trace a les effets suivants :

  • Google Cloud Les services 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 ignore 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 journal, de métrique et de trace.

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

Compatibilité avec VPC Service Controls

Google Cloud Les services et vos applications peuvent envoyer des données de trace à votre projet à l'aide de l'API Cloud Trace ou de l'API Telemetry. Les services de visualisation fournis par Cloud Trace utilisent l'API Cloud Trace pour récupérer les données de trace qu'ils affichent :

  • Cloud Trace est un service compatible avec VPC Service Controls. Le nom du service Trace est cloudtrace.googleapis.com. Pour en savoir plus et connaître les limites, consultez Produits compatibles : Cloud Trace.

  • L'API Telemetry est un service compatible avec VPC Service Controls. Le nom du service est telemetry.googleapis.com. Pour en savoir plus et connaître les limites, consultez Produits compatibles : API Telemetry.

Pour définir des valeurs par défaut qui spécifient la Google Cloud région dans laquelle vos données de trace sont stockées et si une clé gérée par le client chiffre les données, utilisez l'API Observability. Vous utilisez également cette API pour configurer des ensembles de données BigQuery associés, qui vous permettent d'interroger vos données de trace à l'aide des services BigQuery, et pour configurer des champs d'application de trace, qui vous permettent d'agréger les données de trace stockées dans plusieurs projets.

  • L'API Observability est un service compatible avec VPC Service Controls. Le nom du service est observability.googleapis.com. Pour en savoir plus et connaître les limites, consultez Produits compatibles : API Observability.

Pour en savoir plus, consultez les ressources suivantes :

Cloud Trace et résidence des données

Si vous utilisez Assured Workloads car 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 segments de trace.

Pour empêcher votre Google Cloud projet de stocker des données de trace, désactivez l' API Cloud Trace. Ne désactivez pas l'API Telemetry, car elle peut recevoir des données de journal, de métrique et de trace.

Conservation des traces

Catégorie Période de conservation
Segments stockés dans le _Trace bucket 30 jours

Rôles IAM

Cloud Trace utilise Identity and Access Management (IAM) pour contrôler l'accès aux ressources. Pour obtenir la liste des rôles de l'API Cloud Trace et de l'API Telemetry, consultez Contrôler l'accès avec IAM.

Étant donné que l'API Telemetry est une API consommateur, l'envoi de données à l'API Telemetry nécessite que vous spécifiiez un projet de quota et que vous accordiez au compte de service de l'application l'autorisation d'utiliser ce quota. Pour en savoir plus, consultez API Telemetry : authentification.

Étape suivante