Examiner les appels MCP à l'aide de Trace

Vous pouvez configurer vos applications agentiques qui appellent des serveurs MCP Google Cloud distants pour permettre à ces serveurs de générer des spans qui enregistrent l'état des appels. Vous pouvez ensuite utiliser Cloud Trace, qui stocke et analyse les spans enregistrant les appels d'outils, les appels de méthodes, ainsi que les requêtes et les réponses, pour vous aider à comprendre le comportement de vos applications agentiques.

Une span enregistre une seule fonction ou opération qui fait partie d'une opération de bout en bout plus vaste. Une trace représente une seule opération de bout en bout et se compose de spans. Par conséquent, une trace fournit des informations sur la séquence de fonctions appelées et la latence globale, tandis qu'un span fournit des informations sur l'état et la latence d'une fonction spécifique.

À 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 invoquent des méthodes d'API Google Cloud . Par exemple, votre application peut appeler l'outil list_log_entries pour extraire les données de journaux récentes.

Le Model Context Protocol (MCP) est une spécification qui définit une manière standardisée pour les agents d'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.

Comment le contexte de trace est transmis à un serveur MCP

Les pages de référence MCP, telles que la documentation pour 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 ressemble à ce qui 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 liste le nom de l'outil, tel que list_log_entries. Le champ arguments contient les informations requises par l'opération pour traiter la demande.

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 la portée d'appel (PARENT_SPAN_ID).
  • Indique si la portée appelante a échantillonné la requête (SAMPLED_FLAG). Ce champ a la valeur 01 lorsqu'il est échantillonné et 00 lorsqu'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'indicateur sampled doit être défini sur 1.

  • Les serveurs MCP Google Cloud distants peuvent générer une seule portée pour une opération tools/call, mais ils ne génèrent pas de portées pour d'autres types d'opérations ni de portées enfants pour l'opération tools/call.

  • Les serveurs MCP Google Cloud distants ne génèrent une portée 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 prennent en charge le traçage. Elle explique également comment vos serveurs MCP auto-hébergés peuvent générer des spans 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 spans 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 une étendue de trace pour une opération tools/call :

Produit Référence
Cloud Logging Référence MCP Cloud Logging
Cloud Monitoring Référence MCP Cloud Monitoring
Maps Grounding Lite Documentation de référence sur le MCP Maps Grounding Lite
GKE Référence GKE MCP
Cloud Run Référence MCP Cloud Run
Compute Engine Documentation de référence sur les MCP Compute Engine
Google Security Operations Référence Google SecOps MCP
AlloyDB pour PostgreSQL Référence MCP AlloyDB pour PostgreSQL
Agent Search Référence MCP pour la recherche d'agents
Cloud SQL
BigQuery Documentation de référence sur MCP BigQuery
Personalized Service Health Référence MCP pour Personalized Service Health
Cloud Billing Référence MCP Cloud Billing
Policy Troubleshooter Référence MCP de Policy Troubleshooter
Managed Service pour Apache Airflow Documentation de référence sur le MCP Managed Service pour Apache Airflow
Datastream Documentation de référence sur le MCP Datastream
Policy Analyzer Référence MCP de Policy Analyzer
Unified Maintenance Référence MCP Unified Maintenance

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 de traces. Cette page vous permet d'afficher des informations agrégées sur vos données de trace, et d'explorer des traces et des spans individuels. Pour en savoir plus, consultez Rechercher et explorer des traces.

Pour afficher les spans écrits par les serveurs MCP, filtrez vos données de trace par nom de span. Par exemple, certains serveurs MCP Google Cloud distants peuvent générer une étendue de trace lorsqu'ils reçoivent une opération tools/call. Ces segments suivent la convention de dénomination suivante :

tools/call NAME

Dans l'expression précédente, NAME fait référence à l'outil appelé, par exemple list_keys. Cette convention de dénomination est définie par les conventions sémantiques OpenTelemetry pour MCP.

Pour trouver ces étendues, 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 sur l'instrumentation, consultez Choisir une approche d'instrumentation.

Les exemples d'instrumentation que nous fournissons utilisent OpenTelemetry :