Opentelemetry on lo0 — Blog Técnico

MCP por dentro y su observabilidad profunda: el LSP de los agentes IA y cómo verlo todo con OpenTelemetry

Wed, 20 May 2026 06:00:00 +0200

TL;DR

Model Context Protocol (MCP) es el estándar que Anthropic publicó a finales de 2024 y que se ha convertido en 2026 en el protocolo dominante para conectar agentes IA con herramientas y datos externos. Su valor —el motivo por el que toda la industria lo ha adoptado en menos de 18 meses— es que resuelve un problema combinatorio: antes de MCP, integrar M apps IA con N herramientas requería M×N integraciones ad-hoc; con MCP, M + N. Es el mismo movimiento que hizo el Language Server Protocol en 2016 para los editores de código. La arquitectura es tres roles bien definidos —Host (la app IA), Cliente (la conexión, uno por servidor) y Servidor (la pieza que expone capacidades)—; las primitivas son seis —tres del lado servidor (Tools, Resources, Prompts), tres del lado cliente (Sampling, Roots, Elicitation)—; el protocolo es JSON-RPC sobre dos transportes —stdio para procesos locales, Streamable HTTP para remoto—. El reto operacional aparece cuando hay 10-20 servers MCP corriendo simultáneamente, cada uno con varias tools, conectados a un agente que encadena llamadas multistep: observar qué pasa, dónde fallan las cosas, cuánto cuesta cada tool, qué tenant invoca qué se vuelve crítico. La respuesta del ecosistema en 2026: las nuevas OpenTelemetry GenAI semantic conventions for MCP (ya estables), trace context propagation vía params._meta (porque JSON-RPC no lo trae nativo), FastMCP con instrumentación OTel built-in, MCP Gateways como capa centralizada (Traefik Hub, MintMCP, OpenObserve), y MCP Inspector para debugging interactivo. Este artículo recorre la arquitectura desde fuera hacia dentro, sitúa cada concepto en su lugar exacto, y baja al detalle de la observabilidad: trazas, métricas RED, casos de uso reales y trampas.

Este es el tercer post de la serie post-tracing. Posts previos: Evals y Guardrails. Aquí bajamos al protocolo que conecta agentes con herramientas, y cómo verlo en producción.

La analogía maestra (en tres versiones)

MCP es un protocolo de comunicación. Como cualquier protocolo, se entiende mejor con la analogía adecuada. Voy a darte tres porque cada una ilumina una faceta distinta y la combinación te deja entendiéndolo mejor que cualquier definición técnica.

Versión 1 — El USB-C de las apps IA (la oficial)

Es la analogía que Anthropic adoptó al presentarlo. Antes de USB-C, cada dispositivo electrónico tenía su propio conector. Tu móvil llevaba microUSB o Lightning, tu portátil un puerto propietario para alimentación, tus auriculares un jack 3.5mm, tu disco externo USB-A en una punta y mini-USB en la otra. Resultado: tres cajas llenas de cables específicos que se perdían, ninguno servía para dos cosas, comprar un dispositivo nuevo significaba comprar accesorios nuevos.

USB-C cambió eso. Un único conector físico que muchos protocolos atraviesan: datos (USB 3, USB 4, Thunderbolt), vídeo (DisplayPort), alimentación (Power Delivery), audio. Conectas cualquier cosa a cualquier cosa y funciona; los protocolos negocian arriba.

MCP juega el mismo rol para apps IA. Antes de MCP, cada aplicación que quería integrar herramientas con un LLM —Claude Desktop, Cursor, Continue, custom agents propios— inventaba su propia forma de hacerlo. Cada vendor de tools tenía que escribir N integraciones distintas, una por app. Resultado: fragmentación masiva, mucho código duplicado, integraciones que se rompían cuando una app cambiaba su API interna.

Con MCP, el conector es uno: cualquier app que hable MCP puede usar cualquier herramienta MCP. Igual que tu USB-C habla a impresoras, monitores y discos sin que la impresora “sepa” que el cable está conectado a un Mac o a un Linux.

Versión 2 — El LSP de los editores de código (la más técnicamente precisa)

Esta es mi preferida porque la analogía es estructuralmente idéntica, no solo metafórica.

Hasta 2016, si querías que tu editor de código soportara un lenguaje nuevo —Rust, Go, TypeScript— alguien tenía que escribir un plugin específico para tu editor concreto. VSCode tenía su plugin de Rust, IntelliJ otro distinto, Vim otro, Emacs otro. Cada feature decente (go-to-definition, autocompletado, refactoring) era una implementación duplicada N veces. M editores × N lenguajes = M·N integraciones.

Microsoft propuso en 2016 el Language Server Protocol (LSP): cada lenguaje implementa un único “language server” (un proceso que entiende ese lenguaje); cada editor implementa un único cliente LSP; cuando trabajas con código Rust en VSCode, VSCode lanza rust-analyzer como subproceso y le habla LSP por stdio. Cualquier editor LSP + cualquier servidor LSP = funciona. M + N.

MCP es literalmente este patrón, trasladado de “editor + language server” a “app IA + tool provider”. Y comparte hasta el detalle técnico: ambos pasan JSON-RPC sobre stdio (entre otros transportes). Cuando Anthropic diseñó MCP, miraron a LSP. Quien venga del mundo de editores e IDEs encontrará MCP familiar.

Versión 3 — El driver del sistema operativo (la operativa)

Por último, una analogía que ayuda a entender lo que hace un MCP server concreto.

Un sistema operativo no sabe directamente cómo hablar con tu impresora HP LaserJet específica. Lo que sabe es una interfaz genérica: “imprimir documento”, “consultar estado”, “cancelar tarea”. El driver de impresora es la pieza que traduce esa interfaz genérica a los comandos propietarios de tu impresora específica.

Un MCP server hace exactamente lo mismo:

Tu agente IA sabe una interfaz genérica: invocar una tool con un schema definido, leer un resource por URI, pedir un prompt template por nombre.
El MCP server es el driver: traduce esas operaciones genéricas a las API concretas del sistema underlying —tu base de datos PostgreSQL, tu filesystem, tu API GitHub, tu Stripe—.

Esto deja al agente IA libre de saber cómo se autentica con GitHub, qué SQL exacto usa PostgreSQL, qué endpoints tiene Stripe. Habla MCP; el server se encarga de los detalles.

Con las tres analogías combinadas: MCP es la capa entre el LLM y el mundo, un USB-C estándar implementado como LSP en JSON-RPC, con cada server actuando de driver para un sistema underlying concreto.

Qué problema concreto resuelve MCP

Antes de bajar a la arquitectura, conviene fijar el problema específico que MCP resuelve, porque sin eso muchas decisiones de diseño parecen arbitrarias.

El problema es el coste cuadrático de las integraciones.

Imagina que tienes M aplicaciones que usan LLMs (Claude Desktop, Cursor, Continue, ChatGPT Desktop, tu propio agente custom, …) y N herramientas externas que esos LLMs podrían usar (filesystem, GitHub, Slack, PostgreSQL, Jira, Notion, …). Sin un estándar:

Cada par (aplicación, herramienta) requiere una integración específica.
Cada vez que la aplicación cambia su API interna, hay que actualizar N integraciones.
Cada vez que la herramienta cambia su API, hay que actualizar M.
Para que tu herramienta nueva sea adoptada, tienes que escribir M integraciones.
Para que tu aplicación nueva soporte el ecosistema, tienes que escribir N.

Resultado real en 2023-2024: fragmentación masiva. Function calling de OpenAI no era compatible con tool use de Anthropic; cada framework (LangChain, LlamaIndex, dspy) tenía su propio wrapper; los plugins de Claude Desktop no funcionaban en Cursor; etc.

MCP rompe la cuadratura. Cada aplicación implementa el protocolo una vez; cada herramienta implementa el protocolo una vez; cualquier par funciona. M + N.

Es exactamente lo que pasó con USB-C, con LSP, con SQL (antes había APIs propietarias por base de datos), con POSIX (antes había APIs propietarias por sistema operativo). El patrón se repite porque resuelve siempre el mismo tipo de problema.

La arquitectura: tres roles, situados con claridad

Vamos a fijar dónde vive cada cosa, porque mezclar los roles es la fuente número uno de confusión en MCP.

Tres roles. Vamos a fijar qué hace cada uno y dónde vive físicamente.

Host: la aplicación IA

El Host es la aplicación que el usuario abre. Claude Desktop, Cursor, Continue, ChatGPT Desktop, un agente custom que tu equipo construye, una extensión de VSCode. Lo que el usuario percibe como “el producto”.

El Host es el responsable de:

Decidir qué servidores MCP conectar (configurados por el usuario en un archivo o vía UI).
Lanzar o conectar con cada servidor MCP.
Crear un Cliente MCP por servidor (es 1:1, no comparten).
Embeber el LLM (o llamarlo vía API) que toma las decisiones de qué herramientas usar.
Mediar la autorización del usuario para acciones sensibles (mostrarle al humano “el agente quiere ejecutar X tool, ¿permites?”).

Importante: el LLM vive dentro del Host, no en los servidores. Los servidores son tontos; ejecutan operaciones cuando se les pide. El razonamiento ("¿debería llamar a esta tool ahora?") vive en el LLM del host.

Cliente: la conexión, una por servidor

Un Cliente MCP es una conexión específica entre el Host y un Servidor. Si tu Host tiene 5 servidores MCP configurados, tiene 5 clientes, no uno compartido. Cada cliente:

Mantiene su socket o stdio pipe con el servidor.
Negocia capacidades en el handshake inicial (qué versión del protocolo, qué primitivas soportan ambos).
Serializa requests JSON-RPC al servidor y deserializa respuestas.
Es el punto donde el Host invoca operaciones del servidor.

La separación 1:1 cliente-servidor es importante porque permite que cada server tenga su propio estado de sesión, sus permisos específicos y su contexto autenticado independiente. No hay multiplexación en el cliente.

Servidor: la pieza que expone capacidades

El Servidor MCP es la pieza que implementa el lado tool-provider del protocolo. Recibe JSON-RPC del cliente, lo procesa, ejecuta la acción contra el sistema underlying y devuelve respuesta.

Hay dos sabores físicamente:

Servidor local: arranca como subproceso del Host, comunica por stdio. Su ciclo de vida es el del Host (cuando cierras Claude Desktop, los servidores locales mueren). Modelo típico: tu Host lanza node filesystem-mcp-server.js como hijo.
Servidor remoto: corre como servicio independiente, accesible por HTTP. Multi-tenant, autenticado, escalable. Modelo típico: una empresa publica https://mcp.acme.com/v1 y muchos hosts se conectan.

Esta diferencia tiene consecuencias enormes en observabilidad (volveremos en breve).

Resumen del lugar de cada cosa

Componente	Vive en	Hay cuántos	Habla qué con quién
Host	Máquina del usuario	1 (la app abierta)	UI con usuario; lanza clientes
LLM	Embebido en Host (o cloud API)	1 (el principal)	Razona; pide tools
Cliente	Host	1 por servidor	JSON-RPC con su servidor
Servidor local	Subproceso del Host	1 por integración local	stdio con su cliente
Servidor remoto	Servicio externo	1 por servicio	HTTP/SSE con sus clientes
Sistema underlying	Externo	Depende	API/DB/FS, no MCP

Si te confundes en discusión, vuelve a esta tabla. La fuente número uno de errores en MCP es decir “el servidor” cuando se quiere decir “el host”.

Las dos capas del protocolo

MCP separa data layer y transport layer. Esta separación es la que permite que el protocolo funcione por stdio local y por HTTP remoto sin cambiar nada en las primitivas.

Data Layer: JSON-RPC con extensiones MCP

La capa de datos define el vocabulario de los mensajes. Es JSON-RPC 2.0. Cada mensaje es un JSON con jsonrpc: "2.0", un method (eg tools/call, resources/read), params, e id para correlar request con response.

Encima de JSON-RPC, MCP añade:

Lifecycle: el handshake inicial (initialize, initialized) que negocia capacidades.
Las primitivas (siguiente sección): tools/*, resources/*, prompts/*, sampling/*, etc.
Notifications: mensajes sin respuesta (eg notifications/cancelled para abortar una tool en curso).
Meta-information: el campo params._meta por convención lleva metadata transversal (trace context, request IDs).

Transport Layer: cómo se mueven los mensajes

La capa de transporte define cómo viajan los mensajes JSON-RPC. Dos transportes oficiales:

stdio: el cliente lanza el servidor como subproceso y se comunican por sus stdin/stdout/stderr con JSON-RPC. Un mensaje por línea, separados por newline. Sin red, sin handshake TLS, sin auth (la confianza se hereda del propio sistema operativo: si lanzas el subproceso, le confías). Latencia mínima (~100 μs round-trip), ancho de banda máximo (memcpy, no socket).

Caso de uso: servidores locales que viven en la misma máquina que el host. La mayoría de servidores MCP que ves en directorios públicos son stdio.

Streamable HTTP: el cliente envía POST a un endpoint HTTP del servidor; el servidor responde con JSON, opcionalmente abre un stream Server-Sent Events para enviar notificaciones asíncronas o respuestas largas. Auth por bearer token, API key o headers custom.

Introducido en la spec de noviembre 2025, sustituye al transporte SSE puro de versiones anteriores que tenía limitaciones de bidireccionalidad. Caso de uso: servidores remotos que sirven a muchos clientes simultáneos, con autenticación y multi-tenancy.

Importante: las primitivas son las mismas en ambos transportes. Un tools/call es idéntico en stdio y en HTTP. El transport es accidental, no fundamental.

Las seis primitivas: situadas en la arquitectura

Aquí está la chicha. Hay seis primitivas en MCP. Suelen confundirse porque varias parecen hacer cosas similares. La clasificación clave: tres viven del lado servidor (server expone, cliente consume) y tres del lado cliente (cliente expone, servidor consume).

Server-side: lo que el servidor le da al host

Tools son acciones que el servidor expone. Cada tool tiene un schema (parámetros tipados, descripción) y una implementación. Cuando el LLM del host decide invocar una tool, el cliente envía tools/call al servidor, este la ejecuta y devuelve resultado.

Ejemplo: el server github-mcp expone create_issue(repo, title, body). El LLM del host decide “voy a crear un issue”, llama esta tool, github-mcp habla a la API de GitHub, devuelve el issue ID al LLM.
Lugar arquitectónico: el servidor las expone, el LLM las consume.

Resources son datos contextuales que el servidor expone, direccionables por URI. No son acciones; son lecturas de contenido. Un resource tiene URI (file:///path/to/doc.md, postgres://table/users), metadata y un endpoint para leer contenido.

Ejemplo: el server filesystem-mcp expone como resources los archivos de los directorios autorizados. El LLM pide resources/read con URI file:///docs/api.md y obtiene el texto.
Lugar arquitectónico: el servidor las expone, el host las lee (y opcionalmente las pasa al LLM como contexto).

Diferencia clave Tools vs Resources: Tools son verbos (ejecutan, modifican estado, tienen side effects); Resources son sustantivos (existen, se leen, son idempotentes). Si tienes algo que es “buscar texto en archivos” → probablemente Tool (acción). Si es “este archivo concreto” → Resource. La distinción importa para auditoría y permisos: tools requieren más control.

Prompts son plantillas de prompt parametrizadas que el servidor expone. El usuario o el host puede invocarlas para inyectar un patrón conversacional al modelo.

Ejemplo: un server code-review-mcp expone un prompt review_diff(diff_text, style="strict") que devuelve un prompt completo bien escrito para pedirle al LLM que revise código.
Lugar arquitectónico: el servidor las expone, el usuario o el host las invoca, el LLM las recibe como input.

Los prompts son la primitiva menos usada de las tres; muchos servers ni los implementan. Pero permiten que un equipo publique buenos prompts como librería reutilizable, separados del agente.

Client-side: lo que el host le da al servidor

Aquí es donde MCP se diferencia de protocolos como HTTP REST: el servidor también puede pedir cosas al host, no es solo una vía. Tres primitivas viajan en esa dirección.

Sampling: el servidor pide al host que ejecute una generación con su LLM. Es decir, el servidor toma prestado el LLM del host para razonar.

Ejemplo: el server search-mcp recibe una query del agente, busca en su corpus, encuentra 50 resultados y necesita resumirlos antes de devolver. En vez de tener su propio LLM, manda un sampling/createMessage al cliente; el host pasa esto a su LLM, ejecuta la generación con permisos del usuario, devuelve el resumen al servidor.
Lugar arquitectónico: el servidor lo pide, el host (con su LLM y la autorización del usuario) lo cumple.
Por qué importa: el usuario controla qué modelo se usa, qué coste se paga, qué permisos aplican. El servidor no necesita su propia API key de OpenAI.

Roots: el host le dice al servidor dónde mirar. Roots son URIs (directorios, repositorios, namespaces) que el host autoriza al servidor a explorar.

Ejemplo: tu Claude Desktop arranca filesystem-mcp con roots [file:///Users/yo/proyectos]. El servidor sabe que solo debe operar dentro de esa carpeta, no en /etc/passwd.
Lugar arquitectónico: el host las declara en el handshake, el servidor las respeta.

Elicitation: el servidor pide al host información adicional al usuario humano vía UI estructurada.

Ejemplo: el server stripe-mcp está a punto de procesar un refund de 5000€. Antes de ejecutar, manda elicitation/createMessage al cliente; el host muestra al usuario “Confirma este refund de €5000” con un botón; cuando el usuario confirma, devuelve OK al server, que entonces procede.
Lugar arquitectónico: el servidor pide, el host muestra al usuario, el usuario decide, la respuesta vuelve al servidor.
Es la primitiva clave para human-in-the-loop en acciones sensibles.

Visualización del flujo de las seis primitivas

 HOST SERVIDOR
│ │
Server-side ─────┼─────────────────────────────────────┤
│ │
tools/list ──────┼────── pregunta qué tools hay ──────▶│
│◀────── devuelve lista ──────────────│
│ │
tools/call ──────┼────── ejecuta esta tool ───────────▶│
│◀────── resultado ──────────────────│
│ │
resources/read ──┼────── lee este URI ────────────────▶│
│◀────── contenido ─────────────────│
│ │
prompts/get ─────┼────── dame este prompt ────────────▶│
│◀────── prompt compilado ──────────│
│ │
Client-side ─────┼─────────────────────────────────────┤
│ │
sampling ────────│◀────── necesito una generación ─────│
│── usa mi LLM ───┐ │
│── devuelve ─────▼──────────────────▶│
│ │
roots ───────────┼─── declarados en handshake ────────▶│
│ │
elicitation ─────│◀────── pregunta al usuario X ───────│
│── muestra UI ──┐ │
│── confirma ────▼───────────────────▶│

El JSON-RPC en acción: un ejemplo concreto

Para que la teoría se materialice, una conversación MCP real entre cliente y servidor filesystem-mcp:

// 1. Handshake inicial (cliente → servidor)
{
"jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": {
"protocolVersion": "2026-03-01",
"capabilities": {
"sampling": {}, // este cliente soporta sampling
"roots": { "listChanged": true }
},
"clientInfo": { "name": "ClaudeDesktop", "version": "1.2.0" }
}
}
// 2. Server responde con sus capabilities
{
"jsonrpc": "2.0", "id": 1, "result": {
"protocolVersion": "2026-03-01",
"capabilities": {
"tools": { "listChanged": true },
"resources": { "subscribe": true, "listChanged": true },
"prompts": {}
},
"serverInfo": { "name": "filesystem-mcp", "version": "0.5.2" }
}
}
// 3. Cliente pide listado de tools
{
"jsonrpc": "2.0", "id": 2, "method": "tools/list"
}
// 4. Server devuelve sus tools con schema
{
"jsonrpc": "2.0", "id": 2, "result": {
"tools": [
{
"name": "read_file",
"description": "Read a file from the filesystem",
"inputSchema": {
"type": "object",
"properties": { "path": { "type": "string" } },
"required": ["path"]
}
},
{ "name": "write_file", "description": "...", "inputSchema": {} },
{ "name": "list_directory", "description": "...", "inputSchema": {} }
]
}
}
// 5. El LLM decide llamar read_file; cliente envía tools/call
{
"jsonrpc": "2.0", "id": 3, "method": "tools/call",
"params": {
"name": "read_file",
"arguments": { "path": "/Users/yo/proyectos/notas.md" },
"_meta": { // ← extensión donde irá trace context
"traceparent": "00-abc123...-def456-01"
}
}
}
// 6. Server devuelve contenido del archivo
{
"jsonrpc": "2.0", "id": 3, "result": {
"content": [
{ "type": "text", "text": "# Mis notas\n\n..." }
]
}
}

Lo importante a notar: params._meta. Ese es el bag donde MCP convencionalmente pasa metadata transversal, incluyendo trace context. Volveremos en breve.

El problema de observabilidad: por qué tracing tradicional no basta

Hasta aquí la teoría. Bajemos al problema operacional: en un cluster de producción 2026, un agente típico tiene 5-15 servidores MCP conectados simultáneamente, cada uno con 5-20 tools, y cada conversación con el agente puede generar decenas de llamadas a tools encadenadas. Sin observabilidad, depurar incidencias es imposible.

Por qué el tracing genérico (Hubble, OTel sin convenciones MCP) no es suficiente:

Stdio no se ve en la red. Los servidores locales hablan por pipes del SO. Tu Hubble o tu Datadog APM no ven nada; no hay paquetes que capturar. AgentSight (visto en el post anterior de la serie eBPF) con stdiocap lo captura pero da el JSON-RPC en crudo, sin contexto semántico (qué tool es, qué resource, qué prompt).

HTTP genérico tampoco entiende MCP. Si trazas el HTTP a un servidor MCP remoto sin convenciones MCP, ves un POST a /v1 con un body JSON-RPC opaco. Pierdes “qué tool se invocó”, “qué argumentos”, “fue elicitation o sampling”. Métricas RED por endpoint no te sirven; necesitas RED por tool.

JSON-RPC no propaga trace context nativo. A diferencia de HTTP (W3C traceparent header) o gRPC (metadata), JSON-RPC no tiene un campo estándar para trace context. Si no propagas, cada llamada al servidor empieza un trace nuevo desconectado del trace del agente.

Multistep multi-server es muy difícil de seguir. Una sola conversación del usuario puede traducirse en: 1) call a github-mcp get_pr; 2) call a filesystem-mcp read_file para varios archivos; 3) llamada al LLM principal con todo el contexto; 4) call a postgres-mcp query; 5) call a slack-mcp send_message. Sin trace context propagado, son cinco traces inconexos. Con propagación, es un árbol.

La solución: OpenTelemetry semantic conventions for MCP, ya estables en 2026.

OpenTelemetry semantic conventions for MCP

Las GenAI MCP semantic conventions son el set de atributos estandarizados para spans y métricas relacionados con MCP. Se publicaron como parte del subgrupo GenAI de OpenTelemetry SIG y son la primera parte de las semantic conventions GenAI que llegó a estable.

Por qué semantic conventions específicas

Antes de tenerlas, los equipos instrumentaban MCP con las RPC semantic conventions genéricas (las que usarías para gRPC o XML-RPC). Funcionaba a medias. Las conventions MCP-específicas añaden:

Atributos para identificar qué primitiva se ejecutó (mcp.method.name = "tools/call").
Atributos para identificar qué tool/resource/prompt concreto se tocó (mcp.tool.name, mcp.resource.uri, mcp.prompt.name).
Atributos para el flujo bidireccional (sampling/elicitation requests del servidor al cliente).
Atributos para el handshake (mcp.protocol.version, mcp.client.name, mcp.server.name).
Métricas RED estandarizadas por tool (mcp.tool.call.duration, mcp.tool.call.errors).

Los atributos canónicos

Los atributos que cualquier instrumentación MCP-aware debería emitir:

Atributo	Significado	Ejemplo
`mcp.method.name`	Método JSON-RPC	`"tools/call"`
`mcp.tool.name`	Nombre de la tool	`"read_file"`
`mcp.resource.uri`	URI del resource	`"file:///docs/api.md"`
`mcp.prompt.name`	Nombre del prompt	`"code_review"`
`mcp.session.id`	ID de sesión MCP	`"sess-abc123"`
`mcp.protocol.version`	Versión del protocolo	`"2026-03-01"`
`mcp.client.name`	Identidad del cliente	`"ClaudeDesktop/1.2.0"`
`mcp.server.name`	Identidad del servidor	`"filesystem-mcp/0.5.2"`
`mcp.transport`	Transporte usado	`"stdio"` o `"http"`
`mcp.error.code`	JSON-RPC error code	`-32602` (Invalid params)
`gen_ai.usage.input_tokens`	Tokens consumidos (si sampling)	`1240`
`gen_ai.usage.output_tokens`	Tokens generados (si sampling)	`512`

Los dos últimos vienen de las semantic conventions GenAI genéricas y se aplican cuando la llamada MCP involucra sampling (servidor usando el LLM del cliente).

Métricas RED por tool

Más allá de los spans, las semantic conventions definen tres métricas core:

mcp.tool.call.duration (histograma): latencia de cada invocación.
mcp.tool.call.count (counter): número total de invocaciones.
mcp.tool.call.errors (counter): errores por tool.

Etiquetadas con mcp.tool.name, mcp.server.name, mcp.client.name. Pivotables en Grafana para responder “qué tool es la más lenta”, “qué tool falla más”, “qué cliente carga más a qué server”.

Trace context propagation: el truco del `params._meta`

JSON-RPC no tiene cabeceras como HTTP, así que MCP no puede usar traceparent header de W3C directamente. La solución que el ecosistema ha consensuado: propagar trace context en params._meta.

Cuando el cliente MCP envía un tools/call, su instrumentación OTel hace:

import json
from opentelemetry.propagate import inject

carrier = {}
inject(carrier) # rellena con traceparent/tracestate del span activo

params = {
 "name": "read_file",
 "arguments": {"path": "/notas.md"},
 "_meta": carrier, # ← propaga trace context
}

Cuando el servidor recibe, hace lo simétrico:

from opentelemetry.propagate import extract

ctx = extract(request.params.get("_meta", {}))
with tracer.start_as_current_span("tools/call", context=ctx):
 # esta span es hija de la del cliente
 return execute_tool(request.params)

Resultado: el span del servidor es hijo del span del cliente en el árbol de traces. Cuando ves la trace en Tempo o Phoenix, ves toda la cadena: usuario → host → cliente → server → ejecución → respuesta → cliente → host → respuesta al usuario.

Esto requiere que ambos extremos instrumenten consistentemente. Si el server no extrae el contexto, ves spans desconectados pero al menos tienes traceability del lado cliente.

Patrones de instrumentación

Hay tres caminos para instrumentar MCP, en orden creciente de esfuerzo:

1. FastMCP con OpenTelemetry built-in

FastMCP es uno de los frameworks Python más usados para construir servidores MCP. Trae instrumentación OpenTelemetry built-in: cada tool, resource template, prompt operation genera spans automáticamente con las conventions MCP correctas.

from fastmcp import FastMCP
from opentelemetry.sdk.trace.export import OTLPSpanExporter

mcp = FastMCP("my-server", otel_endpoint="https://otel-collector:4318")

@mcp.tool()
def search_docs(query: str) -> str:
 """Search the corpus for matching documents."""
 # esto genera automáticamente un span con
 # mcp.tool.name=search_docs, mcp.method.name=tools/call, etc.
 return run_search(query)

Cero código de instrumentación. Spans con conventions correctas. Es el patrón recomendado si arrancas un servidor MCP en Python desde cero.

2. OpenTelemetry SDK manual

Para servidores ya existentes o en otros lenguajes (TypeScript, Go), la opción es instrumentar manualmente con el SDK estándar OTel + emitir los atributos MCP convencionales:

from opentelemetry import trace
tracer = trace.get_tracer(__name__)

async def handle_tools_call(req: JSONRPCRequest):
 ctx = extract_trace_context(req)
 with tracer.start_as_current_span("mcp.tools.call", context=ctx) as span:
 span.set_attribute("mcp.method.name", "tools/call")
 span.set_attribute("mcp.tool.name", req.params["name"])
 span.set_attribute("mcp.server.name", "filesystem-mcp")
 try:
 result = await execute_tool(req.params)
 return result
 except Exception as e:
 span.set_attribute("mcp.error.code", -32603)
 span.record_exception(e)
 raise

Más boilerplate pero funciona con cualquier servidor existente.

3. MCP Inspector para debugging interactivo

MCP Inspector (oficial) es una herramienta de debugging interactivo a nivel protocolo. Lanza un proxy local (puerto 6277) entre tu cliente y el servidor, y abre una UI web (puerto 6274) donde ves cada mensaje JSON-RPC ida y vuelta en tiempo real.

No es observabilidad de producción —es desarrollo y depuración—. Pero es insustituible durante el bring-up de un servidor nuevo: ves exactamente qué requests llegan, qué responses se devuelven, qué errores se producen. Ahorra horas de logging ad-hoc.

MCP Gateways: la pieza centralizada para enterprise

Cuando tu organización tiene muchos agentes conectándose a muchos servidores MCP, gestionar la matriz de conexiones se vuelve operacionalmente serio. La pregunta natural —"¿puede haber un proxy delante de todos los MCP servers que centralice auth, rate limiting, logging y observabilidad?"— ya tiene respuesta: MCP Gateways.

Un Gateway MCP es un proxy que:

Acepta conexiones MCP de los hosts/agentes.
Las enruta a los servers MCP backend correspondientes.
Aplica autenticación y autorización centralizada (qué agente puede llamar qué tool).
Aplica rate limiting por agente, por tool, por tenant.
Observa: emite métricas OTel de cada operación pasante.
Propaga identidad del agente al servidor backend (con varios modelos: token forwarding, token exchange, impersonación).

Las opciones que se han establecido en 2026:

Traefik Hub MCP Gateway — del equipo de Traefik. Configuración declarativa, integración nativa con el ecosistema Kubernetes/Helm de Traefik.
MintMCP — gateway con foco en observabilidad y multi-tenancy. SaaS y self-host.
OpenObserve MCP Gateway — integrado con la plataforma de observabilidad OpenObserve.

Para deployments pequeños (un equipo, pocos agentes) un Gateway puede ser overkill. Para enterprise (decenas de agentes, decenas de servers, compliance regulado), es prácticamente obligatorio.

Casos de uso reales de la observabilidad MCP

Vamos a aterrizar con cinco casos donde la observabilidad MCP propiamente instrumentada da valor inmediato:

1. Audit por tool, por tenant, por agente

Pregunta: “¿quién ejecutó la tool delete_repo el mes pasado?”. Sin observabilidad MCP, imposible. Con conventions OTel + propagación de identidad: query en tu backend de traces filtrando por mcp.tool.name="delete_repo", agrupando por mcp.client.name o por user_id propagado en _meta. Compliance feliz.

2. Coste por tool y por tenant

Pregunta: “¿cuánto cuesta cada tool?”. Si las tools invocan APIs externas (Stripe, OpenAI sampling) o consumen recursos significativos (GPU para una tool de inferencia), saber su coste agregado importa. Con mcp.tool.call.duration + gen_ai.usage.* agregadas por tool y tenant, se construyen dashboards de cost accountability sin instrumentar nada extra.

3. Debug de cadenas multistep que fallan

Pregunta: “el agente falló al completar esta tarea, ¿dónde fue?”. El trace propagado conecta: span del usuario → span del LLM con su CoT → spans de cada tool invocada → span del LLM final. Si la cadena se rompió en la tercera tool, en Tempo se ve el span rojo con el mensaje de error específico. Reproducir el fallo es trivial.

4. Latencia y degradación de tools

Pregunta: “¿qué tool está degradando?”. Métricas RED por tool en Grafana muestran latencia p95/p99 a lo largo del tiempo. Cuando una tool empieza a subir de 200ms a 800ms (porque el servicio underlying se está colapsando), lo ves antes de que los usuarios se quejen.

5. Detección de loops y anomalías agentic

Pregunta: “¿algún agente está atascado en bucle?”. Si un agente llama tools/call read_file 80 veces en 30 segundos para el mismo path, claramente algo está mal. Alerta sobre mcp.tool.call.count agrupado por (session_id, tool_name) detecta esto. Combinado con detección de loops a nivel de razonamiento, cierra el círculo.

Trampas operativas

Falta de identity propagation

Tu Gateway autentica al agente, pero pasa requests al backend sin propagar identidad. Resultado: los logs del backend dicen “service-account” en todo, imposible auditar quién invocó qué. Elige una estrategia de propagación temprano: token forwarding (sencillo, expone tokens al backend), token exchange (más seguro), o impersonación con logging cruzado.

Servidores stdio que no aparecen en tu APM

Es la trampa nº1 del campo. Tu agente Cursor usa filesystem-mcp como stdio; no ves nada en Datadog porque no hay tráfico de red. Solución: instrumentar el servidor stdio con OTel SDK que exporta por OTLP a tu collector (vía gRPC o HTTP, OTel collector puede recibir aunque el server hable stdio con su cliente). O usar AgentSight stdiocap para capturar el JSON-RPC en crudo y procesarlo offline.

Múltiples versiones de protocolo en producción

Diferentes clientes usan distintas versiones de MCP simultáneamente. Tu metrics dashboard mezcla peras y manzanas. Etiqueta SIEMPRE con mcp.protocol.version y filtra/agrupa por ella.

`_meta` perdido al pasar por proxy

Tu Gateway acepta el request del cliente, lo reescribe para el backend, y se olvida de copiar params._meta. Resultado: trace roto en el Gateway, dos traces inconexos. Asegúrate de que tu Gateway preserva o re-inyecta trace context en cada hop.

Volumen de trazas con servers chatty

Algunos servers MCP emiten muchas pequeñas operaciones (filesystem listings, partial reads). Sin sampling, llenan tu backend de trazas inútiles. Aplica tail-based sampling que conserve sesiones completas o solo conserve traces con errores/latencia alta.

Cardinalidad en métricas

mcp.tool.call.duration con mcp.session.id como label explota la cardinalidad. No incluyas IDs únicos por sesión en labels; mantén la cardinalidad bajo control con labels que toman pocos valores discretos (tool name, server name, client name, error code).

Confundir spans del cliente y del servidor

Cuando ves el árbol, distingue: el cliente ve latencia total desde su perspectiva (incluye network); el servidor ve solo su trabajo. Si miras solo el span del servidor para depurar latencia percibida por el usuario, te pierdes el RTT. Usa ambos.

Lo que no hemos cubierto

MCP transport WebSocket experimental: alternativa a Streamable HTTP, aún no estándar.
Servidores MCP en cloud-native deployments con sidecars: patrón emergente de desplegar MCP servers como sidecars de pods.
MCP federation: composición de varios servers como uno solo (similar a GraphQL federation).
eBPF + MCP: cómo stdiocap de AgentSight y los hooks de Cilium se complementan con la instrumentación nativa.
MCP testing y contract tests: cómo validar que tu servidor cumple la spec.

Referencias

Especificación y conceptos:

Model Context Protocol — sitio oficial — entrada canónica.
MCP architecture overview.
Transports — MCP docs.
MCP Inspector (GitHub) — debugging interactivo.

OpenTelemetry GenAI MCP:

Semantic conventions for Model Context Protocol — OpenTelemetry — referencia normativa.
Adding OpenTelemetry Trace Support to MCP (Discussion #269) — historia de la propuesta.
How to Instrument MCP Servers with OpenTelemetry (OneUptime).
How to trace MCP server tool calls with OpenTelemetry and Elastic APM.
MCP Observability with OpenTelemetry (SigNoz).
Distributed tracing for agentic workflows (Red Hat Developer).
OpenTelemetry for AI Agents in MCP Workflows (MintMCP).

Frameworks y gateways:

FastMCP OpenTelemetry — instrumentación built-in.
Traefik Hub MCP Gateway — gateway de Traefik.
MintMCP — gateway con foco en observabilidad.
OpenObserve MCP Gateway guide.
What is an MCP Gateway (DEV Community).
OpenTelemetry MCP Server (Traceloop) — el patrón inverso: usar MCP para que agentes consulten traces OTel.

Cross-references:

Post anterior: Guardrails y safety.
AgentSight y el nuevo tracing de LLMs — donde se introdujo stdiocap para capturar stdio de servidores MCP locales.
Evals: la capa después del tracing.

AgentSight y el nuevo tracing de LLMs: zero-instrumentation con eBPF frente a Langfuse, LangSmith, Phoenix y compañía

Tue, 19 May 2026 18:00:00 +0200

TL;DR

Observar un agente de LLM en producción en 2026 se divide en dos enfoques con filosofías opuestas. El instrumentado, dominante hasta 2025, vive en herramientas como Langfuse, LangSmith, Arize Phoenix, Helicone, OpenLLMetry/Traceloop o Pydantic Logfire: instalas un SDK, decoras tus llamadas, emites spans con la convención OpenTelemetry GenAI (gen_ai.request.model, gen_ai.usage.input_tokens, etc.) y los exportas a un backend. Profundidad altísima cuando controlas el código; cero visibilidad cuando el agente es un binario opaco que ejecutas sin instrumentar. El zero-instrumentation, que AgentSight ha popularizado en la segunda mitad de 2025, gira la perspectiva 180º: pone hooks eBPF en las uprobes de las bibliotecas SSL/TLS y captura el plaintext de cada petición HTTPS antes del cifrado, sin tocar el código de la app, con menos del 3% de overhead y la garantía de ser tamper-proof (el agente no puede falsificar lo que se ve en el kernel). Combinado con captura BPF de stdio para servidores MCP locales, AgentSight te da observabilidad completa de cualquier agente —incluyendo binarios cerrados como Claude Code, Gemini CLI o Cursor— en un cluster Kubernetes. Las dos familias no son enemigas: la pila de referencia 2026 combina ambas (instrumented para apps propias con LangChain, eBPF para binarios opacos y compliance de tamper-proof) sobre OpenTelemetry GenAI semantic conventions como vocabulario común que el ecosistema está estabilizando este año.

Este es el cuarto y último post de la serie sobre eBPF. Parte 1: eBPF de cero a Cilium. Parte 2: Tetragon: seguridad de runtime. Parte 3: Hubble: observabilidad de red. Aquí cerramos el círculo con la dimensión semántica —qué hace un agente IA, no solo qué red abre o qué syscalls emite—.

La analogía: APM tradicional vs sniffer de red

Quien haya operado aplicaciones empresariales conoce las dos tribus del monitoring. La tribu APM (New Relic, AppDynamics, Datadog APM): instalas un agente o un SDK en cada aplicación, marcas spans, recoges traces con profundidad enorme dentro de cada proceso —líneas de código, queries SQL, métodos de Java—. La tribu wire-level (sniffers de red, herramientas tipo SolarWinds NPM, NetFlow): no toca la aplicación; observa el cable, ve protocolos, latencias, retransmisiones, identifica problemas que la app no sabe que tiene.

Cada una ve cosas distintas y las dos sirven. Quien ha vivido un incidente serio donde APM decía “todo verde” mientras los usuarios sufrían sabe que el wire-level habría detectado el problema (un middlebox saturado, un MTU mal configurado, un timeout de TCP). Quien ha intentado debuggear un memory leak con sniffers sabe que sin APM era imposible.

La observabilidad de agentes LLM en 2026 está exactamente en este punto. El APM-style lleva un par de años montado: Langfuse, LangSmith, Phoenix, OpenLLMetry. Profundidad enorme, requiere instrumentar la app. El wire-level con eBPF acaba de llegar: AgentSight es el primer proyecto que lo lleva a productivo. Profundidad menor en el interior del agente, pero ve cualquier agente sin tocar nada y es tamper-proof. Los dos sirven. La industria está en plena coexistencia.

Por qué observar agentes LLM es distinto

Antes de entrar en herramientas, vale la pena detenerse en qué hace específicos a los agentes LLM como sujetos de observabilidad:

No-determinismo. El mismo input puede producir outputs distintos. Reproducir un incidente requiere capturar exactamente la conversación, el modelo, los parámetros y, idealmente, la seed. Una métrica agregada “latencia p95” se queda corta; lo que necesitas es replay de la traza individual.

Cadena de invocaciones externas. Un agente típico llama LLM → herramientas (tool calling) → MCP servers → otras APIs → vuelta a LLM. Una sesión de chat puede generar decenas de llamadas encadenadas que hay que correlar por trace_id para entender la decisión.

Coste lineal en tokens. Cada llamada se paga en tokens. Sin trazar input/output tokens por petición, no puedes asignar coste a tenant ni equipo, ni detectar bucles que se comen tu presupuesto en una hora.

Riesgo semántico. Prompt injection (un user input que contiene instrucciones para manipular al modelo), jailbreaks, leakage de secretos via tool calls. Es un tipo de problema que no aparece en aplicaciones tradicionales y la observabilidad debe verlo.

Binarios opacos. En 2026, muchos equipos despliegan agentes de terceros —Claude Code, Cursor agent, Aider, Gemini CLI, Codex CLI— como herramientas internas. No son aplicaciones propias; son binarios cerrados que llaman a la API del vendor. Instrumentarlos es imposible. Observarlos requiere otra cosa.

Multi-agent y orquestación. Cada vez más arquitecturas tienen agentes que invocan a otros agentes (planner → executor → critic). La observabilidad debe entender la topología, no solo el span individual.

Con estos cinco puntos en mente, las herramientas que vamos a ver se diferencian principalmente en qué partes del problema cubren bien y qué partes dejan ciegas.

El enfoque instrumentado: cómo funciona

El modelo es directo y conocido:

Tu código llama al LLM o a herramientas usando una librería oficial: openai, anthropic, langchain, llama_index, dspy.
Instalas un SDK del tracer (Langfuse, LangSmith, OpenLLMetry, Logfire) que wrappea o monkey-patcha esas librerías.
Cada llamada emite un span OpenTelemetry con atributos estandarizados: modelo usado, tokens input/output, latencia, parámetros, mensajes, herramienta invocada, resultado.
Los spans se exportan vía OTLP a un backend que los muestra como un árbol de traces.

# Ejemplo típico con OpenLLMetry + cualquier SDK
from traceloop.sdk import Traceloop
from openai import OpenAI

Traceloop.init(app_name="my-agent", api_endpoint="https://otel-collector:4318")

client = OpenAI()
# este call emite automáticamente un span con
# gen_ai.request.model, gen_ai.usage.input_tokens, etc.
resp = client.chat.completions.create(
 model="gpt-4.1",
 messages=[{"role": "user", "content": "..."}]
)

Lo que ves después: un dashboard con cada conversación como un trace, cada llamada como un span, los prompts y completions completos (si optas in), el coste calculado, latencias por span, errores marcados.

OpenTelemetry GenAI semantic conventions: el vocabulario común

La fragmentación del campo se está mitigando con OpenTelemetry GenAI Semantic Conventions. Es el esfuerzo de la CNCF para que todas las herramientas emitan spans con los mismos nombres de atributos:

gen_ai.system — el proveedor (openai, anthropic, vertex_ai, etc.).
gen_ai.request.model — modelo solicitado (gpt-4.1, claude-3-5-sonnet).
gen_ai.response.model — modelo realmente usado (a veces difiere, eg fallbacks).
gen_ai.usage.input_tokens y gen_ai.usage.output_tokens — contadores.
gen_ai.request.temperature, gen_ai.request.top_p, etc. — parámetros.
gen_ai.response.finish_reasons — por qué terminó (stop, length, content_filter).
gen_ai.operation.name — el tipo de operación (chat, embedding, completion).

A principios de 2026, los client spans salieron de experimental a estable. El resto (server spans, multi-agent events) sigue en desarrollo. El significado operacional: si tu SDK emite estos atributos, cualquier backend que entienda OTel GenAI puede consumirlos. Cambiar de Langfuse a Phoenix a Helicone no implica re-instrumentar, solo cambiar el exporter.

La SIG está activamente desarrollando conventions for multi-agent systems: agent teams, tasks, actions, memory, artifact tracking. Esto es lo que falta para que las arquitecturas de agentes complejas tengan vocabulario común. En 2026 está experimental; se espera estabilización a finales de año o principios de 2027.

Herramientas instrumentadas: el panorama 2026

Herramienta	Licencia	Self-host	Foco	Donde brilla
Langfuse	MIT	Sí	LLM observability + evals + prompt mgmt	Mejor balance OSS, suite completa
LangSmith	Comercial	No	LangChain/LangGraph nativo	Si usas LangChain, integración cero-config
Arize Phoenix	ELv2 (OSS)	Sí	OTel-native, RAG fuerte	Vector DBs, retrieval, embeddings
Helicone	Comercial + OSS lite	Sí (lite)	Proxy simple	Setup minutos, OpenAI-only
OpenLLMetry / Traceloop	Apache 2.0	Sí	SDK OTel para LLMs	Vendor-neutral, exporta a cualquier OTel backend
Pydantic Logfire	Comercial	No	App + LLM unificado	Si usas Pydantic AI, integración nativa
Weights & Biases Weave	Comercial	Limitado	Experimentación + producción	Si ya usas W&B para training
Laminar / Braintrust	Comercial	No / Sí	Evals + tracing	Más recientes, foco en evaluación

Deep dive: Langfuse

Merece detenerse en Langfuse porque es, en 2026, la elección por defecto entre las opciones open-source y la que más equipos han adoptado este año. Es proyecto de YC W23, licencia MIT, y lleva un ritmo de release sostenido con cambios arquitectónicos serios entre versiones.

Cuatro pilares declarados: observability (tracing), evaluations, prompt management, playground/datasets. Cada uno por separado tiene productos comerciales completos detrás; Langfuse los integra en una sola plataforma con un solo backend.

El SDK v4: OTEL-native, no un sustituto

El gran cambio operacional reciente es el SDK v4, una capa fina sobre el cliente oficial de OpenTelemetry. La elección es deliberada: en lugar de mantener un cliente propio que se atrase respecto a las primitives OTel, Langfuse usa el SDK estándar y enriquece los spans con atributos y helpers específicos para LLM. La consecuencia: cualquier código que ya esté instrumentado con OpenTelemetry vainilla (@opentelemetry/sdk-node, opentelemetry-sdk en Python) puede exportar a Langfuse sin cambios mayores, y al revés, si mañana quieres migrar de Langfuse a otro backend OTel, los spans son portables.

En Python el decorador idiomático es @observe:

from langfuse import observe, get_client

langfuse = get_client()

@observe()
def buscar_documentos(query: str):
 # cualquier llamada interna también se traza
 return vector_store.similarity_search(query)

@observe(as_type="generation")
def llamar_llm(prompt: str):
 # marcada como "generation" para que aparezca con metadata LLM
 return openai_client.chat.completions.create(...)

@observe()
def pipeline_rag(pregunta: str):
 docs = buscar_documentos(pregunta)
 return llamar_llm(build_prompt(pregunta, docs))

El árbol de llamadas se captura automáticamente: la traza muestra pipeline_rag como root span, con buscar_documentos y llamar_llm como hijos, anidados. Sin escribir un solo with tracer.start_as_current_span(...) a mano.

En TypeScript el equivalente es modular: instalas @langfuse/tracing, @langfuse/otel y @opentelemetry/sdk-node, y puedes usar decoradores TS, context managers o spans manuales —los tres modelos interoperan—. La consecuencia: bibliotecas terceras que emiten spans OTel (openai, @anthropic-ai/sdk, instrumentaciones de Vercel AI SDK) se ven en Langfuse sin trabajo adicional.

Arquitectura self-host: pensada para producción seria

La arquitectura del backend Langfuse tiene dos decisiones explícitas que distinguen su despliegue self-host:

Persistencia primero en S3/Blob Storage. Cuando un evento de tracing entra, se persiste en object storage antes de tocar la base de datos. Solo cuando el procesado posterior confirma OK se inserta en Postgres/Clickhouse. Si la DB cae temporalmente, los eventos no se pierden; quedan en S3 esperando reproceso. Para producción donde perder traces de un incidente equivale a perder evidencia, esto es load-bearing.
Migraciones largas como background jobs. Los upgrades de schema que en otras plataformas implican ventana de downtime, en Langfuse se ejecutan en background mientras la aplicación sigue sirviendo. El downtime de upgrade se reduce drásticamente.

Los modos de despliegue soportados oficialmente:

Docker Compose: para desarrollo y POCs. Un comando, todo arriba.
VM: un único nodo, contenedores, sin orquestación. Para entornos pequeños.
Kubernetes con Helm: el modo recomendado para producción. Chart oficial mantenido. Soporta external Postgres, external Clickhouse, external S3, HPA.

Las dependencias externas en producción típica: Postgres (metadata, prompts, configuración), Clickhouse (eventos de tracing, queries de alta cardinalidad), S3 o blob compatible (eventos pendientes), Redis (cola entre componentes). Sí, son varias piezas; es lo que sostiene la durabilidad y la escala.

Prompt management como ciudadano de primera clase

Lo que diferencia a Langfuse de las plataformas centradas solo en tracing es que los prompts viven en Langfuse, no en el repo de la aplicación o en hojas de cálculo. Cada prompt tiene:

Nombre y versión (v1, v2, v3…). Cambiar el prompt no requiere redeploy de la app: la app pide el prompt al SDK, que lo cachea y refresca cuando hay versión nueva.
Variables tipadas: {{user_input}}, {{context}}. Render con validación.
Tags y labels: por entorno (production, staging), por equipo, por experimento.
Cache cliente y servidor: el SDK cachea localmente con TTL configurable, evita roundtrip a Langfuse en cada llamada.
Linkage con traces: cada trace recoge qué versión exacta de qué prompt se usó. Investigar “esta respuesta salió mal” lleva al prompt versión Y, no a “alguna versión del prompt en algún momento”.

from langfuse import get_client

langfuse = get_client()

prompt = langfuse.get_prompt("rag-system-prompt", version=3)
# o por label: langfuse.get_prompt("rag-system-prompt", label="production")

compiled = prompt.compile(context=docs_text, user_input=question)
# 'compiled' es el string final, listo para mandar al LLM

Para equipos que iteran sobre prompts a diario, esto es lo que evita el caos de “qué versión del prompt está corriendo realmente en producción ahora mismo”.

Evaluations: cuatro modelos de evaluación combinables

Langfuse cubre los cuatro patrones de evaluación de respuestas:

LLM-as-a-judge: configuras un modelo (típicamente GPT-4 o Claude) con una rúbrica y evalúa cada respuesta. Resultado: score numérico (0-1) y justificación. Aplicable a tracing automático (todas las respuestas) o batch (selección de dataset).
User feedback: la app permite al usuario marcar respuesta como buena/mala. El feedback se asocia al trace y al prompt version, lo que permite ver qué versiones tienen peor rate.
Manual labeling: una UI donde labelers humanos puntúan respuestas. Útil para datasets dorados y para evaluar el judge.
Custom evaluators vía API/SDK: evals propios (un test unitario, una métrica de negocio) reportan score vía API. Se integran con CI.

Combinadas, dan regression testing del prompt: cambias de v3 a v4, evalúas el dataset dorado con LLM-as-judge, comparas; si v4 empeora en alguno de los segmentos, el merge falla.

Integraciones

Langfuse no compite con OpenLLMetry, LangChain o LiteLLM: los integra. Las que están testeadas y documentadas:

OpenTelemetry: cualquier instrumentación OTel emite a Langfuse vía OTLP.
LangChain y LangGraph: callback nativo que captura toda la cadena.
LlamaIndex: callback nativo.
OpenAI SDK (Python y TS): wrapper que añade tracing automáticamente.
LiteLLM: integración como callback, lo que cubre 100+ proveedores via LiteLLM.
OpenLLMetry / Traceloop: emiten a Langfuse como cualquier backend OTel.
MLflow: vía exporter OTel desde MLflow a Langfuse.
Vercel AI SDK: instrumentación nativa.

La estrategia es clara: Langfuse es backend, no SDK. Tu equipo elige cómo instrumenta; Langfuse acepta cualquier camino. La consecuencia operativa: cambiar de Langfuse a otro backend OTel mañana es viable.

Cuándo Langfuse no es la respuesta

Para no presentarlo como bala de plata:

Si solo usas LangChain y no tienes recursos para self-host: LangSmith te dará integración más fluida (es el mismo equipo).
Si tu única necesidad es proxy con cost tracking sin evals: Helicone es más simple.
Si quieres una solución vendor commercial integrada: Datadog LLM Observability, New Relic AI Monitoring o Dynatrace AI son alternativas Enterprise con soporte 24/7.
Si tu carga es batch puro de inferencia masiva sin agentes: probablemente no necesitas tracing semántico; Prometheus + Grafana con métricas OTel basta.

Para todo lo demás —apps propias con tracing serio, multi-tenant con cuotas, equipos que iteran prompts a diario, RAG con evaluación continua—, Langfuse es la apuesta segura.

Resumen de elección rápido:

LangChain → LangSmith (cero esfuerzo, instrumentación automática).
Aplicaciones propias multi-framework con OSS → Langfuse (MIT, self-host, completo).
RAG con vector stores → Arize Phoenix (mejor visibilidad de retrieval).
Proxy simple, presupuesto bajo → Helicone.
Vendor neutrality estricta → OpenLLMetry/Traceloop.
Pydantic AI → Logfire (mismo equipo).

Fortalezas y debilidades del modelo instrumentado

Fortalezas:

Profundidad enorme: spans anidados con todo el contexto (chain steps, retrieval, embeddings, tool calls).
Vocabulario semántico: SDK conoce el dominio (LLM, vector store, agent).
Madurez: tres años de evolución, ecosistema rico, dashboards listos.
Evals integradas: las plataformas top combinan tracing con evaluación (judge LLM, datasets, regression).

Debilidades:

Requiere control del código: si no puedes instrumentar, no funciona.
Trust en la app: si la app reporta mal o tiene un bug, la traza también. No es tamper-proof.
Acoplamiento al SDK: cambios de versión de una librería pueden romper la instrumentación.
Cobertura desigual: SDKs de Python están maduros; Go, Rust, JS más jóvenes.

El enfoque zero-instrumentation: AgentSight

AgentSight es el proyecto del grupo eunomia-bpf que abandera el enfoque opuesto. Su paper en arxiv (2508.02736), presentado en el Workshop on Practical Adoption Challenges of ML for Systems, formaliza la propuesta. La premisa es directa:

Instead of instrumenting the agent, observe it at the system boundary.

Y “system boundary” significa el límite del kernel: el último punto antes de que un dato salga del proceso hacia la red o el filesystem. Ahí, con eBPF, se ven las cosas tal como son, sin que la aplicación pueda cooperar para esconderlas.

Arquitectura: tres planos

AgentSight monta tres capas:

Plano 1 — SSL/TLS uprobes. eBPF puede atar programas a funciones de bibliotecas userspace (uprobes). Las funciones objetivo son las de cifrado: SSL_write, SSL_read de OpenSSL/BoringSSL, equivalentes en Rustls. AgentSight les pone hooks que capturan los argumentos: el buffer plaintext que la app pasa para que sea cifrado, justo antes de que TLS lo procese. En la recepción, hace lo simétrico: hook después de SSL_read con el plaintext recién descifrado. Resultado: AgentSight ve el contenido completo de cualquier petición HTTPS que la app haga sin necesidad de man-in-the-middle ni certificados ni descifrar tráfico. El payload es plaintext porque se capturó antes de cifrarse.

Esto funciona porque las uprobes son baratas (~100 ns por invocación) y porque las apps usan bibliotecas de TLS comunes. Las pocas apps que implementan su propio TLS (raras en producción) escapan a este hook; para esas hace falta un kprobe diferente o instrumentación manual.

Plano 2 — Kernel events. Paralelamente, AgentSight observa syscalls relevantes a través de tracepoints: execve (qué procesos arrancan), connect/accept (red), read/write con file descriptors (filesystem y stdio), unlink, clone. Cualquier acción del agente que tenga efecto fuera del proceso pasa por aquí. Esto cubre, entre otros, comandos shell ejecutados por el agente —si un agente Claude Code decide ejecutar rm -rf para “limpiar el proyecto”, el execve se ve aunque la API LLM no lo reporte—.

Plano 3 — Correlation engine. Los dos planos anteriores producen streams de eventos asíncronos. AgentSight tiene un componente en userspace que los correlaciona causalmente cross-process: una petición HTTP saliente con bash -c rm -rf puede ser correlada con la respuesta LLM previa que la sugirió, vía PIDs, tiempos y heurísticas. El paper menciona el uso opcional de un LLM secundario (Anthropic Claude por ejemplo) que analiza la secuencia de eventos y produce alertas semánticas: “el agente respondió con una tool call que no estaba en la whitelist”, “la cadena de reasoning lleva 47 iteraciones sin converger”.

`stdiocap`: capturar stdio de servidores MCP locales

Una pieza específica que merece mención propia es stdiocap, una herramienta BPF separada incluida en el repo. El Model Context Protocol (MCP), popularizado por Anthropic en 2024 y mainstream en 2025-2026, tiene dos modos de transport: HTTP/SSE (red) y stdio (entre el cliente y el server que arranca como subproceso). Los servidores MCP locales —los que corren en la misma máquina y son arrancados por el cliente como hijos vía pipes— comunican por stdin/stdout/stderr con JSON-RPC.

stdiocap engancha read/write/dup sobre los file descriptors de stdin/stdout/stderr de un proceso target y registra todo el tráfico JSON-RPC entre cliente y server MCP. Es la misma idea que la captura SSL pero para stdio: observas la conversación sin que ni el cliente ni el server lo sepan. Caso de uso típico: ver qué tools del MCP server filesystem-mcp ha invocado un agente Claude Code en la última hora, qué argumentos pasó, qué errores recibió. Imposible con instrumentación clásica (los servers MCP suelen ser binarios de terceros).

Garantías: tamper-proof, kernel safety, <3% overhead

Tres propiedades hacen a AgentSight interesante para producción:

Tamper-proof: la observación ocurre en el kernel (uprobes, syscalls). Una aplicación maliciosa o comprometida no puede falsificar lo que se ve. Comparar con instrumentación: si el agente decide no emitir el span de su acción, no aparece en Langfuse. Aquí no tiene elección.
Kernel safety: eBPF verifica formalmente que los programas terminen y respeten bounds checks. No puede crashear el kernel. Igual que en el resto de la serie eBPF.
<3% CPU overhead medido sobre cargas reales de agentes (paper). El número compara favorablemente con instrumentación SDK que típicamente añade 5-10% en aplicaciones intensas.

Lo que detecta out of the box

El paper y la documentación destacan tres clases de detección:

Prompt injection en tiempo real: el correlation engine puede aplicar reglas o un modelo de detección sobre el plaintext capturado por las uprobes SSL. Si el prompt contiene patrones sospechosos —“ignore all previous instructions”, system prompt embebido en un user input, instrucciones para exfiltrar datos—, marca alerta.
Reasoning loops que gastan recursos: agentes que entran en bucles infinitos llamando a herramientas sin progresar. Detectables porque la cadena causal no converge a “respuesta final” y los tokens se acumulan. El correlation engine los marca.
Bottlenecks en multi-agent: cuando varios agentes coordinan, AgentSight ve la matriz de comunicaciones entre todos y puede detectar agentes que se bloquean esperando, deadlocks, fan-out excesivo.

El choque y la coexistencia

Las dos familias parecen competir, pero en realidad ven cosas distintas y se complementan en producción.

Lo que solo el instrumentado ve

Variables internas del agente que no salen al cable: el estado intermedio de un chain LangChain, los valores antes de pasarlos a una herramienta, el cómo se construye un prompt a partir de un template con vars internos.
Spans semánticos profundos: retrieval > embed > vector_search > rerank > format_context > prompt_template > llm. AgentSight ve solo la llamada final al LLM; el camino para construirla es invisible.
Evaluaciones: scoring de respuestas, judge LLMs, regresión de calidad. Esto vive solo en plataformas instrumentadas.

Lo que solo eBPF ve

Binarios opacos: Claude Code, Cursor, Gemini CLI, agentes de terceros. No tienes el código; no puedes instrumentarlos. Solo eBPF los ve.
Acciones a nivel sistema: el agente decide ejecutar git push --force o kubectl delete. La acción se ve en el execve. La instrumentación del agente puede no reportarla (especialmente si fue un comando que el agente generó como output sin pasar por una “tool” explícita).
Tamper-proof audit: para compliance regulatorio (HIPAA, SOC2, NIS2), tener observación que la app no puede burlar tiene valor formal. eBPF lo da.
MCP servers locales con stdio: invisibles para instrumentación clásica salvo que cada server emita sus propios spans (raro).

Lo que ambos ven, complementariamente

Prompts y completions: instrumentado los emite con metadata rica; eBPF los captura del cable. Cross-check perfecto para detectar discrepancias.
Llamadas a APIs externas: APM lo marca; eBPF lo confirma a nivel kernel.
Latencia: APM por span; eBPF mide RTT a nivel TCP y conectividad red.

Matriz de decisión

Caso	Instrumentado	eBPF (AgentSight)
App propia con LangChain	Sí, primero	Opcional
App propia multi-framework	Sí	Opcional
Binario de terceros (Claude Code, Cursor)	No funciona	Sí, único camino
Cumplimiento normativo tamper-proof	Insuficiente	Sí, requerido
Multi-tenant zero-trust	Insuficiente	Sí, requerido
Servidores MCP locales (stdio)	Difícil	Sí, con stdiocap
Evaluación de calidad de respuestas	Sí, requerido	No (fuera de scope)
Profundidad de chain interno	Sí, requerido	No (caja negra para AgentSight)
Reasoning loop detection	Posible con plumbing	Sí, integrado
Prompt injection en tiempo real	Posible (post-procesado)	Sí, en stream

La conclusión natural: para apps propias, instrumentado; para binarios opacos o compliance, eBPF; para todo lo importante, ambos.

Arquitectura de referencia 2026

Cuatro recetas que cubren el grueso de los casos reales:

Setup A — Aplicación propia con LangChain o similar

Necesidades: profundidad, evals, equipo cómodo con SDKs.

Langfuse self-host o LangSmith cloud como backend.
OpenLLMetry SDK o LangSmith SDK instrumentando el código.
OpenTelemetry Collector entre la app y el backend para flexibilidad de routing (a Langfuse + Tempo + Loki por ejemplo).
Hubble para la capa de red en el cluster (latencia inter-pod, drop attribution).

Setup B — Productivizar un binario opaco (Claude Code, Gemini CLI)

Necesidades: observar sin tocar, auditar, controlar coste.

AgentSight desplegado como DaemonSet sobre el cluster (o standalone en el nodo).
Grafana con dashboards alimentados por las métricas de AgentSight.
Exportador OTLP de AgentSight a un backend OTel (Tempo, Jaeger). Los spans usarán las semantic conventions GenAI cuando se estandaricen del todo.
Tetragon opcional para política sobre qué puede ejecutar el agente (Sigkill si intenta rm -rf o similar).

Setup C — Plataforma multi-tenant zero-trust

Necesidades: agentes de distintos clientes corriendo en el mismo cluster, auditoría obligatoria, ninguno confía en el otro.

AgentSight como capa de auditoría tamper-proof. Compliance lo requiere.
Langfuse multi-tenant para los clientes que sí instrumentan.
Tetragon con TracingPolicyNamespaced por tenant (políticas distintas por namespace).
Hubble con flow logs persistentes para forensics.
Cilium NetworkPolicy para aislar tenants entre sí en red.

Setup D — Servidor MCP local en una workstation

Necesidades: ver qué hace un agente con un MCP server stdio.

AgentSight stdiocap apuntando al PID del cliente o del server.
Captura JSON-RPC completo a fichero o a un endpoint OTLP.
Visualización: Grafana o simplemente jq sobre el log.

Caso de uso real: si estás integrando un MCP server propio y quieres ver qué tool calls hace un agente Claude Code o Cursor a tu server, stdiocap es la forma más limpia. No necesitas modificar ni cliente ni server.

Trampas operativas

Datos sensibles en prompts (instrumentado)

Por defecto, Langfuse, LangSmith y similares capturan el contenido completo de prompts y completions. Si tu app procesa PII, secretos, datos médicos, eso va a tu backend de observabilidad. Configurar redacción o content-opt-out antes de pasar a producción es obligado. OTel GenAI tiene flags específicos (OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false) para evitarlo.

Datos sensibles en prompts (AgentSight)

Mismo problema, peor: AgentSight captura literalmente lo que va al cable, plaintext. Si el agente conversó con api.openai.com con un prompt que contenía datos sensibles, AgentSight tiene ese plaintext. Hay que cifrar o redactar antes de almacenar.

Certificados pinned o TLS no estándar

Algunas apps de seguridad alta hacen certificate pinning o usan implementaciones de TLS no convencionales (Go’s crypto/tls, BoringSSL custom). En esos casos, las uprobes a libssl no las cubren. AgentSight detecta cuándo no puede observar y reporta gap; igual hay que añadir hooks específicos al SDK alternativo.

Volumen de tokens y storage

Una aplicación con tráfico medio puede generar millones de tokens al día. Si los almacenas todos en Langfuse o Phoenix con retención largos, la base de datos crece deprisa. Estrategias: sampling agresivo, retención corta para sesiones normales y larga solo para errores/anomalías, redaction de contenido y guardar solo metadata.

Tracing con sampling y consistencia

Para reducir coste, muchas instalaciones samplean: solo 1 de cada N traces se persiste. Cuidado con el sampling no consistente: un trace puede llevar varios spans en múltiples servicios, y si la decisión de samplear se toma per-span, acabas con traces incompletos. OTel tiene head sampling (en el SDK al principio) que es consistente, y tail sampling (en el collector al final) que permite reglas más finas. Para LLM, el tail sampling es ideal: muestrea todo, descarta solo las traces “normales” y conserva las que tienen errores, latencia alta o cost alto.

Multi-agent y trace propagation

Cuando agente A llama a agente B, hay que propagar el trace context (W3C Trace Context headers) para que se vea como un árbol único. Si no lo haces, ves dos traces inconexos. Las plataformas modernas lo hacen automáticamente con inject/extract, pero si tu transport entre agentes es custom (vía Redis pub/sub, vía DB), tienes que propagar a mano.

Coste de las uprobes en bibliotecas críticas

Hookear libssl añade ~100 ns por invocación. En cargas de tráfico TLS extremo (decenas de miles de conexiones/s por core), eso suma. AgentSight lo mantiene por debajo de 3% en cargas típicas de agentes (que son chatty pero no networking-intensive). Si tu uso fuese sniffing de todo el HTTPS del nodo, podría doler más.

Lo que no hemos cubierto (próxima serie)

Evals: la siguiente capa después de tracing. Phoenix, Langfuse, LangSmith y compañía ofrecen evaluación de respuestas (judge LLM, datasets, regression). Es un mundo aparte.
Guardrails y safety: NeMo Guardrails, Llama Guard, Llama Prompt Guard, evaluadores específicos para prompt injection y jailbreaks.
MCP server observability profunda: cómo OpenTelemetry GenAI conventions están extendiéndose a MCP servers para trace-aware tools.
eBPF + on-device inference: cuando el LLM corre localmente vía vLLM o llama.cpp, las uprobes pueden ver la cola tokens-output ANTES de que vayan al cliente. Territorio nuevo.
Análisis estadístico de flows de agentes: detectar drift, outliers, patrones que indican degradación.

Cerrando la serie eBPF

Esta serie de cuatro artículos ha recorrido eBPF desde el primer principio hasta la frontera 2026:

eBPF de cero a Cilium — qué es eBPF, hooks de networking, cómo Cilium se salta la pila TCP/IP, BGP Control Plane v2.
Tetragon: seguridad de runtime — observabilidad y enforcement de procesos en el kernel.
Hubble: observabilidad de red — flow logs L3-L7 y la frontera con los agentes IA.
Este — AgentSight, tracing de LLMs, instrumentado vs zero-instrumentation.

Si has llegado hasta aquí tienes el mapa para sentarte con un equipo de plataforma, de seguridad o de IA en 2026 y reconocer qué hace cada pieza, qué problema resuelve y por dónde empezar. Toda esa pila —Cilium para CNI y BGP, Tetragon para seguridad de runtime, Hubble para observabilidad de red, AgentSight para agentes IA— compartiendo eBPF como sustrato común, gobernanza Cloud Native y vocabulario OpenTelemetry. Es la arquitectura limpia que la industria pidió hace una década y por fin existe.

Referencias

AgentSight:

AgentSight GitHub (eunomia-bpf) — el proyecto.
AgentSight: System-Level Observability for AI Agents Using eBPF (arxiv 2508.02736) — paper formal.
AgentSight ACM workshop publication.
AgentSight blog post (eunomia.dev) — descripción accesible.

OpenTelemetry GenAI semantic conventions:

Plataformas instrumentadas:

Langfuse — MIT, self-host + cloud.
LangSmith — LangChain team.
Arize Phoenix — OSS, OTel-native.
Helicone — proxy simple.
OpenLLMetry (Traceloop) — Apache 2.0, SDK OTel.
Pydantic Logfire — AI observability.

Comparativas 2026:

Cross-references de la serie:

eBPF de cero a Cilium.
Tetragon: seguridad de runtime.
Hubble: observabilidad de red.
Serie de inferencia LLM: KV cache, vLLM en Kubernetes, PagedAttention, Operators LLM K8s.

Opentelemetry on lo0 — Blog Técnico

MCP por dentro y su observabilidad profunda: el LSP de los agentes IA y cómo verlo todo con OpenTelemetry

TL;DR

La analogía maestra (en tres versiones)

Versión 1 — El USB-C de las apps IA (la oficial)

Versión 2 — El LSP de los editores de código (la más técnicamente precisa)

Versión 3 — El driver del sistema operativo (la operativa)

Qué problema concreto resuelve MCP

La arquitectura: tres roles, situados con claridad

Host: la aplicación IA

Cliente: la conexión, una por servidor

Servidor: la pieza que expone capacidades

Resumen del lugar de cada cosa

Las dos capas del protocolo

Data Layer: JSON-RPC con extensiones MCP

Transport Layer: cómo se mueven los mensajes

Las seis primitivas: situadas en la arquitectura

Server-side: lo que el servidor le da al host

Client-side: lo que el host le da al servidor

Visualización del flujo de las seis primitivas

El JSON-RPC en acción: un ejemplo concreto

El problema de observabilidad: por qué tracing tradicional no basta

OpenTelemetry semantic conventions for MCP

Por qué semantic conventions específicas

Los atributos canónicos

Métricas RED por tool

Trace context propagation: el truco del params._meta

Patrones de instrumentación

1. FastMCP con OpenTelemetry built-in

2. OpenTelemetry SDK manual

3. MCP Inspector para debugging interactivo

MCP Gateways: la pieza centralizada para enterprise

Casos de uso reales de la observabilidad MCP

1. Audit por tool, por tenant, por agente

2. Coste por tool y por tenant

3. Debug de cadenas multistep que fallan

4. Latencia y degradación de tools

5. Detección de loops y anomalías agentic

Trampas operativas

Falta de identity propagation

Servidores stdio que no aparecen en tu APM

Múltiples versiones de protocolo en producción

_meta perdido al pasar por proxy

Volumen de trazas con servers chatty

Cardinalidad en métricas

Confundir spans del cliente y del servidor

Lo que no hemos cubierto

Referencias

AgentSight y el nuevo tracing de LLMs: zero-instrumentation con eBPF frente a Langfuse, LangSmith, Phoenix y compañía

TL;DR

La analogía: APM tradicional vs sniffer de red

Por qué observar agentes LLM es distinto

El enfoque instrumentado: cómo funciona

OpenTelemetry GenAI semantic conventions: el vocabulario común

Herramientas instrumentadas: el panorama 2026

Deep dive: Langfuse

El SDK v4: OTEL-native, no un sustituto

Arquitectura self-host: pensada para producción seria

Prompt management como ciudadano de primera clase

Evaluations: cuatro modelos de evaluación combinables

Integraciones

Cuándo Langfuse no es la respuesta

Fortalezas y debilidades del modelo instrumentado

El enfoque zero-instrumentation: AgentSight

Arquitectura: tres planos

stdiocap: capturar stdio de servidores MCP locales

Garantías: tamper-proof, kernel safety, <3% overhead

Lo que detecta out of the box

El choque y la coexistencia

Lo que solo el instrumentado ve

Lo que solo eBPF ve

Lo que ambos ven, complementariamente

Matriz de decisión

Arquitectura de referencia 2026

Setup A — Aplicación propia con LangChain o similar

Setup B — Productivizar un binario opaco (Claude Code, Gemini CLI)

Setup C — Plataforma multi-tenant zero-trust

Setup D — Servidor MCP local en una workstation

Trampas operativas

Datos sensibles en prompts (instrumentado)

Trace context propagation: el truco del `params._meta`

`_meta` perdido al pasar por proxy

`stdiocap`: capturar stdio de servidores MCP locales