Observer les agents MCP avec OpenTelemetry devient indispensable dès qu’un assistant IA appelle vos outils en production. Un agent qui répond lentement, se trompe d’outil ou enchaîne dix appels là où deux suffiraient ne lève aucune alerte classique : le processus tourne, le port répond, et pourtant l’expérience se dégrade et la facture grimpe.
La bonne nouvelle, c’est qu’un appel d’outil MCP n’est rien d’autre qu’une opération distribuée : un client envoie une requête, un serveur la traite, éventuellement en appelant d’autres services. Les traces distribuées, que les équipes SRE connaissent déjà, s’y appliquent directement, à condition de choisir les bons noms de spans et les bons attributs.
Cet article montre comment tracer un serveur et un agent MCP, quels attributs suivre, et comment en tirer des indicateurs de latence et d’erreur exploitables.
Pourquoi observer les agents MCP avec OpenTelemetry ?
Dans une architecture MCP (décrite dans notre guide du Model Context Protocol), une seule question de l’utilisateur peut déclencher une cascade : appel au modèle, choix d’un outil, requête vers le serveur MCP, puis appels du serveur vers une base, une API ou une plateforme d’observabilité. Sans trace, chaque maillon est une boîte noire.
OpenTelemetry apporte trois choses : un format standard, indépendant du fournisseur ; des conventions sémantiques communes pour nommer les opérations d’IA générative ; et la propagation du contexte, qui relie l’agent, le serveur MCP et les services en aval dans une même trace. C’est la même logique que celle décrite pour OpenTelemetry de bout en bout, appliquée à un nouveau type d’appel.
Ce que doit contenir un span d’appel d’outil
Un span décrit une opération : un nom, un type (kind), un début et une fin, un statut, des attributs, éventuellement des événements. Pour MCP, les conventions sémantiques GenAI d’OpenTelemetry, encore au statut « development », proposent un vocabulaire précis.
Un nom à faible cardinalité
Le nom recommandé suit la forme {méthode MCP} {cible}, par exemple tools/call chercher_runbooks. On y met le nom de l’outil, jamais ses arguments ni un identifiant, pour que les appels se regroupent proprement dans les vues d’analyse.
Les attributs utiles
mcp.method.name: la méthode JSON-RPC (tools/call,resources/read…) ;gen_ai.operation.name=execute_tooletgen_ai.tool.name: ce qui permet de traiter un appel MCP comme n’importe quel appel d’outil d’agent ;mcp.protocol.version,mcp.session.idetjsonrpc.request.idpour le diagnostic ;mcp.resource.uripour les lectures de ressources ;error.typeen cas d’échec.
Les arguments et résultats d’outils existent aussi comme attributs optionnels (opt-in). Ils sont précieux pour déboguer, mais peuvent contenir des données personnelles ou des secrets : ne les activez qu’en connaissance de cause.
Un contexte qui traverse le protocole
Le contexte de trace HTTP ne suffit pas : une même requête HTTP peut porter plusieurs messages MCP, et stdio n’a pas d’en-têtes. Les conventions prévoient donc d’injecter traceparent (et éventuellement baggage) dans le champ params._meta de chaque requête MCP. Le serveur l’extrait et rattache son span à celui du client.
En pratique
Étape 1 — Activer les spans du serveur
Bonne surprise si votre serveur utilise le SDK Python officiel en version 2 : il émet déjà un span de type SERVER pour chaque message reçu, avec les attributs ci-dessus. Il ne dépend que de l’API OpenTelemetry ; tant qu’aucun SDK n’est installé, ces spans ne coûtent quasiment rien. Pour les collecter, il suffit d’ajouter le SDK et un exportateur OTLP :
pip install opentelemetry-sdk opentelemetry-exporter-otlp
Pour les autres SDK et frameworks, vérifiez dans leur documentation si une instrumentation existe ou si vous devez créer ces spans vous-même.
Étape 2 — Configurer l’export
La configuration standard passe par des variables d’environnement. Pour un envoi direct vers Dynatrace, l’endpoint OTLP de l’environnement et un jeton d’API autorisé à ingérer des traces sont nécessaires ; vérifiez l’URL et la portée exactes dans la documentation :
export OTEL_SERVICE_NAME=runbooks-mcp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=https://VOTRE-ENV.live.dynatrace.com/api/v2/otlp
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Api-Token%20<JETON>"
Dans le code, initialisez le fournisseur de traces au démarrage, avant de lancer le serveur. Attention en transport stdio : n’utilisez jamais un exportateur console qui écrirait sur la sortie standard, réservée au protocole.
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(provider)
Étape 3 — Tracer l’agent côté client
Côté agent, enveloppez chaque tour de raisonnement dans un span parent. Les appels d’outils effectués à l’intérieur s’y rattachent, et le SDK propage le contexte vers le serveur quand les deux côtés l’utilisent :
tracer = trace.get_tracer("agent-astreinte")
async def traiter_question(client, question: str):
with tracer.start_as_current_span("invoke_agent agent-astreinte") as span:
span.set_attribute("gen_ai.operation.name", "invoke_agent")
resultat = await client.call_tool(
"chercher_runbooks", {"mots_cles": question}
)
span.set_attribute("agent.outils_appeles", 1)
return resultat
L’attribut agent.outils_appeles est un exemple d’attribut maison : préfixez vos attributs personnalisés pour ne pas les confondre avec les conventions officielles.
Étape 4 — Distinguer les types d’erreurs
Un appel d’outil peut échouer de deux façons : une erreur d’exécution renvoyée au modèle (le résultat porte un indicateur d’erreur, le modèle peut réessayer) ou une erreur de protocole JSON-RPC. Dans les deux cas, le span du serveur doit passer en statut d’erreur avec un error.type renseigné. Testez-le volontairement avec un argument invalide et vérifiez ce qui arrive dans votre backend.
Étape 5 — Construire les indicateurs
Une fois les spans dans Grail, une requête DQL suffit pour suivre latence et erreurs par outil. Les noms de champs dépendent de l’ingestion ; adaptez-les à ce que vous voyez dans vos traces :
fetch spans, from: now() - 24h
| filter gen_ai.operation.name == "execute_tool"
| summarize appels = count(),
erreurs = countIf(isNotNull(error.type)),
p95 = percentile(duration, 95),
by: { gen_ai.tool.name }
| sort appels desc
À partir de là, fixez des objectifs simples : latence au 95e centile par outil, taux d’erreur, nombre moyen d’appels d’outils par question. Une hausse brutale de ce dernier signale souvent un agent qui tourne en rond.
Bonnes pratiques
- Nommer les spans par méthode et outil, jamais par argument ou identifiant.
- Suivre les conventions GenAI et MCP, et préfixer les attributs maison.
- Laisser désactivée par défaut la capture des arguments et résultats d’outils.
- Propager le contexte de trace de l’agent jusqu’aux services appelés par le serveur.
- Ne jamais écrire de télémétrie sur la sortie standard d’un serveur stdio.
- Croiser ces traces avec les journaux d’audit décrits pour sécuriser un serveur MCP.
Questions fréquentes
Les conventions MCP d’OpenTelemetry sont-elles stables ?
Non, elles sont au statut « development » et ont été déplacées dans un dépôt dédié aux conventions GenAI. Les noms d’attributs peuvent encore évoluer.
Faut-il instrumenter le client, le serveur, ou les deux ?
Les deux idéalement : le client montre le parcours de l’agent, le serveur montre le coût réel de chaque outil. La propagation du contexte les relie.
Mon serveur Python est-il tracé sans rien faire ?
Avec le SDK officiel en version 2, les spans sont créés automatiquement ; il reste à installer un SDK OpenTelemetry et un exportateur. Voir aussi notre tutoriel pour créer un serveur MCP en Python.
Conclusion
Un agent MCP n’échappe pas aux règles de l’observabilité : chaque appel d’outil mérite un span, avec un nom stable, des attributs standard et un statut fiable. En s’appuyant sur les conventions d’OpenTelemetry et sur la télémétrie intégrée au SDK Python, on obtient rapidement latence, erreurs et comportement des agents dans les mêmes vues que le reste de la production.
Pour aller plus loin : OpenTelemetry series: Anatomy of an OTel span (blog Dynatrace, en anglais).
span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC ni aux projets cités. Les marques citées appartiennent à leurs propriétaires. Les outils évoluent vite : vérifiez les commandes et options dans leur documentation officielle.
5 comments