Observabilidad de agentes: ver lo que tu agente realmente hace

Los logs, el seguimiento de costes y el soporte de OpenTelemetry convierten una sesión de caja negra en datos rastreables, algo esencial en cuanto los agentes funcionan de forma automatizada o en equipo.

Por qué importa observar

Mientras trabajas solo e interactivamente con un agente, ves directamente lo que pasa. En cuanto los agentes funcionan de forma automatizada, en equipo o en CI/CD, necesitas datos reales para eso: qué hizo el agente, cuánto costó, qué herramientas se llamaron.

Los logs de sesión como capa base

Claude Code escribe cada sesión como un archivo JSONL en el disco (en ~/.claude/projects/). El formato es interno y cambia entre versiones: no analices estos archivos directamente, usa /export o las interfaces documentadas. Incluso con planes de suscripción, /usage muestra un desglose de costes y uso directamente en el terminal.

Seguimiento de costes en el terminal

El comando /usage muestra el coste estimado y el uso de tokens de la sesión actual directamente en el terminal, desglosado por skills, subagentes, plugins y servidores MCP individuales. La cifra es una estimación local calculada a partir de recuentos de tokens, no una factura oficial.

OpenTelemetry para la visión de conjunto

A nivel de equipo u organización, Claude Code ofrece soporte nativo de OpenTelemetry: con CLAUDE_CODE_ENABLE_TELEMETRY=1 exportas métricas, eventos y opcionalmente trazas a tu propio backend de observabilidad (Prometheus, Grafana, Datadog, etc.). Así obtienes costes, uso de herramientas y eventos de seguridad de forma centralizada para todas las personas usuarias, en lugar de recopilar logs de cada máquina por separado.

EJEMPLO

`export CLAUDE_CODE_ENABLE_TELEMETRY=1`, `export OTEL_METRICS_EXPORTER=otlp` y `export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317` antes de iniciar `claude` bastan para enviar métricas a una instalación local de OpenTelemetry Collector.

🛠️ EJERCICIO — PRUÉBALO TÚ

Activa localmente la transparencia de costes y sesión en Claude Code, sin montar una pila de observabilidad externa.

Ejecuta /usage en una sesión activa de Claude Code y lee el desglose por skills, subagentes y servidores MCP.
Abre /usage y consulta el desglose de costes y uso.
Configura de prueba CLAUDE_CODE_ENABLE_TELEMETRY=1 y OTEL_METRICS_EXPORTER=console, reinicia claude y observa qué métricas aparecen en la consola.

✅ AUTOEVALUACIÓN

☐ ¿Pudiste saber, con /usage, qué parte de la sesión (por ejemplo, un servidor MCP concreto) consumió más contexto?
☐ ¿Qué contenía la línea JSONL? ¿Te bastó para reconstruir el coste?
☐ ¿Cuál de las variables OTEL_LOG_* NO activarías en una configuración de equipo real porque exporta datos demasiado sensibles?

QUIZ RÁPIDO

¿Cuál es la forma más sencilla de activar la exportación de OpenTelemetry en Claude Code?