Cloud Trace vous permet d'analyser le comportement et les performances des applications agentives qui appellent des serveurs MCP Google Cloud distants. Vous pouvez instrumenter votre application pour enregistrer les prompts, les réponses et les appels de méthode, tandis que les serveurs MCP distants génèrent des segments pour les appels d'outils. Une trace capture l'opération de bout en bout pour afficher les séquences d'appels et la latence globale, tandis que les segments individuels fournissent des détails sur l'état et le temps d'exécution de fonctions spécifiques.
À propos des outils
Les outils permettent à un agent de collecter des informations en dehors de ses données d'entraînement, généralement en interagissant avec des API externes. Avec les serveurs MCP Google Cloud, vos applications agentiques peuvent appeler des outils qui appellent des méthodes d'API Google Cloud . Par exemple, votre application peut appeler l'outil list_log_entries pour récupérer les données de journaux récentes.
Le Model Context Protocol (MCP) est une spécification qui définit une méthode standardisée permettant aux agents IA de communiquer et d'interagir avec des outils, des sources de données et des ressources externes. Pour obtenir la liste complète des produits qui fournissent un serveur MCP et des liens vers leur documentation de référence, consultez Produits compatibles.
Transmission du contexte de trace à un serveur MCP
Les pages de référence MCP, telles que la documentation de list_log_entries, fournissent un exemple de commande curl que vous pouvez utiliser pour envoyer des requêtes HTTP à l'outil. La charge utile JSON envoyée dans la requête se présente comme suit :
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "NAME",
"arguments": {
// provide these details according to the tool's MCP specification
}
},
"id": 1
}
La valeur du champ name indique le nom de l'outil, par exemple list_log_entries.
Le champ arguments contient les informations requises par l'opération pour traiter la requête.
La norme MCP définit un champ _meta, qui permet aux clients et aux serveurs d'associer des métadonnées à leurs interactions. Les clients et les serveurs peuvent utiliser ce champ pour transmettre le contexte de trace :
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "NAME",
"arguments": {
// provide these details according to the tool's MCP specification
},
"_meta": {
"traceparent": "00-TRACE_ID-PARENT_SPAN_ID-SAMPLED_FLAG",
"tracestate": "Vendor specific information."
},
},
"id": 1
}
Les données _meta incluent un champ traceparent. Le format de la valeur de ce champ est défini par l'en-tête traceparent du World Wide Web Consortium (W3C). La valeur inclut les éléments suivants :
- Version de la spécification
traceparent(00). - ID de la trace (TRACE_ID).
- ID de l'intervalle d'appel (PARENT_SPAN_ID).
- Indique si l'intervalle d'appel a échantillonné la requête (SAMPLED_FLAG). Ce champ a la valeur
01lorsqu'il est échantillonné et00lorsqu'il ne l'est pas.
Le champ tracestate contient des informations de traçage spécifiques au fournisseur.
Limites
Le contexte de trace doit respecter la norme W3C Trace Context, et l'option
sampleddoit être définie sur 1.Les serveurs MCP Google Cloud distants peuvent générer un seul span pour une opération
tools/call, mais ils ne génèrent pas de spans pour d'autres types d'opérations ni de spans enfants pour l'opérationtools/call.Les serveurs MCP Google Cloud distants ne génèrent un span que lorsque la requête est authentifiée, autorisée et qu'elle passe d'autres vérifications internes.
Serveurs MCP compatibles avec le traçage
Cette section liste les serveurs Google et Google Cloud MCP distants qui sont compatibles avec le traçage. Il explique également comment vos serveurs MCP auto-hébergés peuvent générer des segments de trace.
Serveurs auto-hébergés
Nous vous recommandons d'instrumenter vos serveurs MCP auto-hébergés pour envoyer des données de télémétrie à votre projet Google Cloud .
Si vous utilisez Python, l'instrumentation peut générer des segments pour les opérations tools/call. Pour en savoir plus, consultez Instrumenter un serveur MCP auto-hébergé avec OpenTelemetry.
Serveurs Google et Google Cloud MCP distants compatibles avec le traçage
Les produits suivants contiennent une intégration qui permet à leur serveur MCP distant de générer un segment de trace pour une opération tools/call :
Configurer votre application
Vous pouvez utiliser n'importe quel framework ou SDK qui transmet le contexte de trace à l'aide du champ _meta. Ces frameworks et SDK incluent ceux qui sont compatibles avec les conventions sémantiques OpenTelemetry pour MCP.
Par exemple, vous pouvez utiliser le framework Agent Development Kit (ADK). Pour en savoir plus, consultez Instrumenter des applications ADK avec OpenTelemetry.
Afficher les segments
Pour afficher vos données de trace, utilisez l'explorateur Trace. Cette page vous permet d'afficher des informations agrégées sur vos données de trace et d'explorer des traces et des segments individuels. Pour en savoir plus, consultez Rechercher et explorer des traces.
Pour afficher les segments écrits par les serveurs MCP, filtrez vos données de trace par nom de segment. Par exemple, certains serveurs MCP Google Cloud distants peuvent générer un segment de trace lorsqu'ils reçoivent une opération tools/call. Ces segments suivent la convention d'attribution de noms suivante :
tools/call NAME
Dans l'expression précédente, NAME fait référence à l'outil appelé, par exemple list_keys. Cette convention d'attribution de noms est définie par les conventions sémantiques OpenTelemetry pour MCP.
Pour trouver ces segments, utilisez la barre de filtre et ajoutez un filtre d'attribut pour mcp.method.name. Définissez la valeur du filtre sur tools/call. Pour en savoir plus sur ces étapes, consultez Afficher les appels aux serveurs MCP distants.
Exemples d'instrumentation
Pour obtenir des recommandations d'instrumentation, consultez Choisir une approche d'instrumentation.
Les exemples d'instrumentation que nous fournissons utilisent OpenTelemetry :
Pour obtenir des exemples utilisant une exportation basée sur un collecteur, consultez les pages suivantes :
Ces exemples envoient des données de journaux, de métriques et de traces au format OpenTelemetry Protocol (OTLP) à votre projet à l'aide de l'API Telemetry.
Pour savoir comment utiliser une exportation directe des données de trace et les envoyer à l'API Telemetry, consultez Migrer de l'exportateur Trace vers le point de terminaison OTLP.
Pour obtenir des exemples montrant comment configurer une application agentique pour collecter des prompts et des réponses, consultez Observabilité pour les développeurs d'agents IA.