Observar agentes MCP con OpenTelemetry: spans de herramientas, atributos, latencia y errores

Observar agentes MCP con OpenTelemetry: spans de llamadas a herramientas, atributos GenAI, propagación del contexto, latencia y errores con DQL.
Observer les agents MCP avec OpenTelemetry : spans d'appels d'outils, attributs, latence et erreurs

Observar los agentes MCP con OpenTelemetry resulta indispensable en cuanto un asistente de IA llama a tus herramientas en producción. Un agente que responde despacio, se equivoca de herramienta o encadena diez llamadas donde bastarían dos no dispara ninguna alerta clásica: el proceso está activo, el puerto responde y, sin embargo, la experiencia se degrada y la factura sube.

La buena noticia es que una llamada a una herramienta MCP no es más que una operación distribuida: un cliente envía una petición, un servidor la procesa, quizá llamando a otros servicios. Las trazas distribuidas, que los equipos SRE ya conocen, se aplican directamente, siempre que se elijan los nombres de span y los atributos adecuados.

Este artículo muestra cómo trazar un servidor y un agente MCP, qué atributos seguir y cómo obtener de ello indicadores de latencia y de error aprovechables.

¿Por qué observar los agentes MCP con OpenTelemetry?

En una arquitectura MCP (descrita en nuestra guía del Model Context Protocol), una sola pregunta del usuario puede desencadenar una cascada: llamada al modelo, elección de una herramienta, petición al servidor MCP y luego llamadas del servidor a una base de datos, una API o una plataforma de observabilidad. Sin trazas, cada eslabón es una caja negra.

OpenTelemetry aporta tres cosas: un formato estándar, independiente del proveedor; convenciones semánticas comunes para nombrar las operaciones de IA generativa; y la propagación del contexto, que une al agente, al servidor MCP y a los servicios posteriores en una misma traza. Es la misma lógica descrita en OpenTelemetry de extremo a extremo, aplicada a un nuevo tipo de llamada.

Qué debe contener un span de llamada a una herramienta

Un span describe una operación: un nombre, un tipo (kind), un inicio y un fin, un estado, atributos y, en su caso, eventos. Para MCP, las convenciones semánticas GenAI de OpenTelemetry, todavía en estado «development», proponen un vocabulario preciso.

Un nombre de baja cardinalidad

El nombre recomendado sigue la forma {método MCP} {destino}, por ejemplo tools/call chercher_runbooks. Se incluye el nombre de la herramienta, nunca sus argumentos ni un identificador, para que las llamadas se agrupen bien en las vistas de análisis.

Los atributos útiles

  • mcp.method.name: el método JSON-RPC (tools/call, resources/read…);
  • gen_ai.operation.name = execute_tool y gen_ai.tool.name: permiten tratar una llamada MCP como cualquier otra llamada a una herramienta de agente;
  • mcp.protocol.version, mcp.session.id y jsonrpc.request.id para el diagnóstico;
  • mcp.resource.uri para las lecturas de recursos;
  • error.type en caso de fallo.

Los argumentos y resultados de las herramientas existen también como atributos opcionales (opt-in). Son valiosos para depurar, pero pueden contener datos personales o secretos: actívalos solo con conocimiento de causa.

Un contexto que atraviesa el protocolo

El contexto de traza HTTP no basta: una misma petición HTTP puede llevar varios mensajes MCP, y stdio no tiene cabeceras. Las convenciones prevén por tanto inyectar traceparent (y, opcionalmente, baggage) en el campo params._meta de cada petición MCP. El servidor lo extrae y enlaza su span con el del cliente.

En la práctica

Paso 1: activar los spans del servidor

Buena sorpresa si tu servidor usa el SDK oficial de Python en versión 2: ya emite un span de tipo SERVER por cada mensaje recibido, con los atributos anteriores. Solo depende de la API de OpenTelemetry; mientras no haya un SDK instalado, esos spans casi no cuestan nada. Para recopilarlos, basta con añadir el SDK y un exportador OTLP:

pip install opentelemetry-sdk opentelemetry-exporter-otlp

Para otros SDK y frameworks, comprueba en su documentación si existe una instrumentación o si tienes que crear esos spans tú mismo.

Paso 2: configurar la exportación

La configuración estándar se hace con variables de entorno. Para un envío directo a Dynatrace, hacen falta el endpoint OTLP del entorno y un token de API autorizado a ingerir trazas; comprueba la URL y el ámbito exactos en la documentación:

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>"

En el código, inicializa el proveedor de trazas al arrancar, antes de lanzar el servidor. Cuidado con el transporte stdio: no uses nunca un exportador de consola que escriba en la salida estándar, reservada al protocolo.

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)

Paso 3: trazar el agente en el lado del cliente

En el lado del agente, envuelve cada turno de razonamiento en un span padre. Las llamadas a herramientas hechas dentro se enlazan a él, y el SDK propaga el contexto hacia el servidor cuando ambos lados lo usan:

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

El atributo agent.outils_appeles es un ejemplo de atributo propio: añade un prefijo a tus atributos personalizados para no confundirlos con las convenciones oficiales.

Paso 4: distinguir los tipos de error

Una llamada a una herramienta puede fallar de dos maneras: un error de ejecución devuelto al modelo (el resultado lleva un indicador de error y el modelo puede reintentar) o un error de protocolo JSON-RPC. En ambos casos, el span del servidor debe pasar a estado de error con un error.type informado. Pruébalo a propósito con un argumento inválido y comprueba qué llega a tu backend.

Paso 5: construir los indicadores

Una vez que los spans están en Grail, una consulta DQL basta para seguir latencia y errores por herramienta. Los nombres de campo dependen de la ingesta; adáptalos a lo que veas en tus trazas:

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

A partir de ahí, fija objetivos sencillos: latencia en el percentil 95 por herramienta, tasa de errores, número medio de llamadas a herramientas por pregunta. Una subida brusca de este último suele indicar un agente que da vueltas en círculo.

Buenas prácticas

  • Nombrar los spans por método y herramienta, nunca por argumento o identificador.
  • Seguir las convenciones GenAI y MCP, y poner prefijo a los atributos propios.
  • Dejar desactivada por defecto la captura de argumentos y resultados de herramientas.
  • Propagar el contexto de traza desde el agente hasta los servicios que llama el servidor.
  • No escribir nunca telemetría en la salida estándar de un servidor stdio.
  • Cruzar estas trazas con los registros de auditoría descritos en proteger un servidor MCP.

Preguntas frecuentes

¿Son estables las convenciones MCP de OpenTelemetry?

No: están en estado «development» y se han trasladado a un repositorio dedicado a las convenciones GenAI. Los nombres de los atributos aún pueden cambiar.

¿Hay que instrumentar el cliente, el servidor o ambos?

Idealmente ambos: el cliente muestra el recorrido del agente y el servidor muestra el coste real de cada herramienta. La propagación del contexto los une.

¿Se traza mi servidor Python sin hacer nada?

Con el SDK oficial en versión 2, los spans se crean automáticamente; falta instalar un SDK de OpenTelemetry y un exportador. Consulta también nuestro tutorial para crear un servidor MCP en Python.

Conclusión

Un agente MCP no escapa a las reglas de la observabilidad: cada llamada a una herramienta merece un span, con un nombre estable, atributos estándar y un estado fiable. Apoyándose en las convenciones de OpenTelemetry y en la telemetría integrada en el SDK de Python, se obtienen enseguida latencia, errores y comportamiento de los agentes en las mismas vistas que el resto de la producción.

Para ir más lejos: OpenTelemetry series: Anatomy of an OTel span (blog de Dynatrace, en inglés).

span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC ni a los proyectos citados. Las marcas citadas pertenecen a sus propietarios. Las herramientas evolucionan rápido: comprueba los comandos y las opciones en su documentación oficial.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Créer un serveur MCP Python pour exposer vos runbooks d'exploitation

Crear un servidor MCP en Python para exponer tus runbooks de operación

Next Post
Observabilité IA de bout en bout : ce que le rachat d'Arize par Dynatrace change, du prototype à la production

Observabilidad de IA de extremo a extremo: qué cambia con la compra de Arize por Dynatrace, del prototipo a producción

Related Posts