Observabilidad en Claude Code: seguimiento de tokens, costes y uso por desarrollador
.webp)
Diseñado para la velocidad: ~ 10 ms de latencia, incluso bajo carga
¡Una forma increíblemente rápida de crear, rastrear e implementar sus modelos!
- Gestiona más de 350 RPS en solo 1 vCPU, sin necesidad de ajustes
- Listo para la producción con soporte empresarial completo
Qué significa la observabilidad para un agente de código
La observabilidad tradicional comprueba si un servicio está activo. Un agente de código siempre está «activo»: se ejecuta en un portátil y se comunica con un proveedor de modelos. La pregunta que realmente importa es de carácter económico y de comportamiento: qué desarrollador ha gastado cuánto, en qué modelo, haciendo qué y por qué una sesión ha costado diez veces más que otra. Se trata de una contabilidad de tokens, no de una comprobación del estado del servicio, y este es el enfoque utilizado en esta guía. Para conocer el reverso de la moneda sobre la facturación, consulte Explicación de los precios de Claude Code.
Lo que está en juego es concreto. Un solo desarrollador activo genera un gasto aproximado de 13 $ por día activo y entre 150 $ y 250 $ al mes, con cerca del 90 % de los usuarios por debajo de los 30 $/día; por lo tanto, las excepciones son enormemente importantes. Sin una vista por desarrollador, es imposible identificar a las tres personas de un equipo de treinta que generan la mayor parte de la factura, ni saber si están realizando un trabajo complejo o simplemente dejando Opus seleccionado por defecto. La observabilidad transforma un total sorprendente en una lista de causas corregibles.
Qué medir realmente
Siete señales concentran casi todo el valor. Todo lo demás se deriva de ellas.
Dos de estas señales —la combinación de modelos y la tasa de caché— representan además sus principales palancas de optimización de costes, motivo por el cual su observabilidad se amortiza por sí sola. La parte del enrutamiento se explica en la Guía de enrutamiento coste vs. capacidad: Opus vs. Sonnet vs. Haiku, y la parte del almacenamiento en caché en Caché de prompts en Claude: el cálculo real de costes.
El token no es un número único: son cuatro
La cifra global de «tokens utilizados» es un agregado inútil porque las cuatro categorías tienen precios drásticamente diferentes. En Opus 5.5 la diferencia es notable: la salida cuesta cinco veces más que la entrada nueva, la escritura en caché cuesta más que la entrada nueva y la lectura en caché cuesta solo una fracción de esta. Combinarlos oculta precisamente la información necesaria para reducir la factura.
Una tasa elevada de lectura en caché es la señal deseada: contexto de larga duración que se reutiliza en lugar de facturarse de nuevo al precio íntegro de entrada. Con una suscripción, la caché de prompts permanece activa cerca de una hora; en la API o en un proveedor en la nube, unos cinco minutos, por lo que la tasa esperada varía según la configuración. Si las lecturas en caché caen y la entrada nueva aumenta, algo ha roto la caché, y esto solo se detecta si los cuatro números se rastrean de forma independiente.
Las opciones nativas y dónde se queda corta cada una
Claude Code incluye visibilidad nativa, pero limitada al ámbito individual.
/usageen la CLI muestra los tokens de la sesión actual y el coste estimado, calculado localmente a precio de tarifa oficial. Es preciso para un único desarrollador en una sola máquina y se reinicia al limpiar la sesión. No permite agregar los datos de un equipo./insightsresume las sesiones recientes en esa máquina: es útil para que el desarrollador analice sus propios patrones, pero sigue sin ofrecer una vista global del equipo.- Las analíticas de suscripción (Teams y Enterprise) ofrecen un informe de gasto a nivel de organización por usuario y por modelo, actualizado diariamente; resulta adecuado para el departamento financiero, pero no ofrece una vista en tiempo real por solicitud.
- El uso en proveedores en la nube es invisible para los paneles de Anthropic. Si ejecuta Claude Code en Amazon Bedrock, Google Vertex o Microsoft Foundry, las analíticas nativas simplemente no lo detectarán, ya que los tokens se facturan directamente a su cuenta de la nube.
El patrón se repite: las herramientas nativas responden a «cuánto acabo de gastar», no a «qué está haciendo todo el equipo en este momento». Para eso, es necesario extraer las métricas de la máquina.
OpenTelemetry: cómo extraer métricas de la máquina
La vía nativa para resolver esta limitación es OpenTelemetry. Claude Code puede exportar métricas de coste y uso de tokens por usuario mediante OTLP hacia su propia plataforma de observabilidad, y funciona en cualquier entorno: suscripción, Console API o cualquier proveedor en la nube. Esto la convierte en la única opción nativa que ofrece cifras por desarrollador casi en tiempo real, independientemente del método de autenticación utilizado.
Cómo activarlo
La exportación está desactivada por defecto y se gestiona íntegramente mediante variables de entorno, configuradas en el perfil de la shell o en un archivo de configuración administrado que se distribuye a cada equipo. Una configuración mínima para métricas y registros:
Las métricas se envían a intervalos determinados (por defecto, 60 000 ms para métricas y 5000 ms para registros), por lo que «casi en tiempo real» significa con una granularidad de un minuto, no por solicitud. Las trazas son una señal en fase beta independiente restringida tras CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 y OTEL_TRACES_EXPORTER=otlp; actívelas únicamente si dispone de un recolector preparado para recibir trazas (spans).
Qué información incluye cada señal
OpenTelemetry emite tres tipos de señales: métricas (los contadores sobre los que se construyen los paneles), registros (eventos discretos) y trazas (spans en fase beta para una única interacción). El desglose de costes se encuentra en las métricas:
La atribución por usuario se basa en los atributos user.email y account-identifier, incluidos de forma predeterminada. Tenga en cuenta que session.id incrementa notablemente la cardinalidad (una serie por sesión), por lo que si su sistema de backend cobra en función de las series de datos, desactívelo en los paneles globales del equipo y atribuya los datos por usuario. Los registros de eventos (claude_code.user_prompt, claude_code.tool_result, claude_code.api_request) aportan detalles por acción que las métricas no pueden ofrecer, y opcionalmente pueden incluir el contenido de los prompts o de las herramientas; se trata de una decisión sobre privacidad que debe valorar antes de su activación.
El inconveniente es operacional: debes instrumentar cada máquina, mantener las variables en su sitio tras renovar portátiles o incorporar personal, y gestionar el colector y los cuadros de mando por tu cuenta. Transmite métricas adecuadamente, pero un flujo de métricas no es un registro de auditoría a nivel de solicitud, y no hace nada para aplicar un presupuesto; solo informa sobre él. Para un análisis más profundo sobre la contabilidad de tokens en sí, consulta Observabilidad para Claude en producción: contabilidad de tokens y trazabilidad.
Nativo frente a OpenTelemetry frente a un gateway
OpenTelemetry y un gateway no son mutuamente excluyentes: un buen gateway es compatible con OpenTelemetry y puede alimentar el mismo stack. La diferencia radica en que el gateway también se sitúa en la ruta de la solicitud, por lo que puede trazar y limitar, no solo contar. OTel es la respuesta adecuada cuando eres propietario de la flota, confías en que cada máquina permanezca instrumentada y solo necesitas generar informes. Un gateway es la respuesta adecuada cuando las máquinas van y vienen, cuando parte del tráfico se ejecuta en un proveedor cloud y cuando "verlo" debe convertirse en "detenerlo".
Observabilidad en el TrueFoundry AI Gateway
Enruta Claude Code a través del TrueFoundry AI Gateway y cada completado cruzará un único punto bajo tu control. Esto transforma la observabilidad: deja de ser algo a lo que cada desarrollador se suma en su portátil y pasa a ser algo que simplemente existe:
- Trazas de solicitudes: cada solicitud con el usuario resuelto, el modelo servido, el desglose de tokens y la latencia, para que puedas responder "quién envió eso y cuánto costó" a posteriori.
- Cuadros de mando de métricas que agregan la flota por usuario, equipo y modelo: la panorámica por desarrollador que se detalla en seguimiento de costes para Claude Code.
- Una vista única para todas las herramientas: Claude Code, Cursor y Codex terminan en el mismo lugar en vez de tres, como se describe en centralización del control de costes para IDE de código con IA.
- Exportación compatible con OpenTelemetry con solo unos 3–4 ms de sobrecarga añadida, de modo que los mismos números fluyen hacia Grafana, Datadog o Prometheus si ya los utilizas.
Qué registra la traza de una sola solicitud
Un gateway responde a preguntas que las métricas de OpenTelemetry no pueden responder porque registra cada solicitud como un registro discreto, no como un contador agrupado por minutos. Una traza captura la identidad resuelta, el modelo servido, el desglose de cuatro vías de tokens, el coste según tu tarifa contratada, la latencia de extremo a extremo en milisegundos, el estado y la decisión de enrutamiento. Dado que cada fila es buscable y se conserva, puedes reconstruir un pico: filtra por un desarrollador y una hora, y lee las llamadas reales que lo impulsaron, el registro de auditoría que un flujo de métricas aplana y omite.
Sobre qué alertar y qué cuadros de mando crear
Recopilar señales es inútil si nadie las consulta hasta que llega la factura. El objetivo de extraer las métricas de la máquina es actuar mientras todavía importa: un conjunto reducido de alertas y unos pocos cuadros de mando, no un muro de gráficos. Las alertas que merecen la pena se corresponden con una causa específica y solucionable:
- Gasto diario por desarrollador que supera un umbral: por ejemplo, mantenerse por encima de los ~$30/día que ya cubren a cerca del 90 % de los usuarios. Esto detecta los casos atípicos el mismo día que comienzan, no un mes después.
- Porcentaje de tokens de Opus por encima de un límite: la señal más clara de desviación del modelo por defecto, donde las ediciones rutinarias se ejecutan silenciosamente en el modelo más caro.
- Caída en la proporción de lecturas de caché: una disminución repentina significa que la caché ha vuelto a empeorar y la entrada nueva se vuelve a facturar a precio íntegro.
- Latencia p95/p99 en ms que supera un límite: saca a la luz la degradación del proveedor y los patrones de tiempo de espera antes de que los desarrolladores informen de que "Claude va lento".
- Volumen de solicitudes fuera del horario laboral: las tareas programadas y el trabajo en segundo plano que reenvían grandes contextos a intervalos fijos se muestran como gasto sin que haya ningún ser humano al teclado.
Los cuadros de mando que merece la pena implementar son igualmente escasos: coste de la flota por desarrollador (top-N), coste por modelo para que la combinación Opus vs. Sonnet vs. Haiku sea visible de un vistazo, una vista apilada de los cuatro tipos de tokens para vigilar la proporción de caché, el coste por repositorio o equipo para imputación de costes, una distribución de latencia en milisegundos y la aceptación de llamadas a herramientas. En un gateway, estos vienen predefinidos y se alimentan automáticamente; en OpenTelemetry los ensamblas en Grafana o en tu backend a partir de las métricas anteriores.
Un ejemplo práctico
Un equipo de plataforma tiene treinta desarrolladores utilizando Claude Code, algunos mediante suscripción y otros en Bedrock. La factura mensual no para de subir y nadie sabe explicar por qué. Apuntan cada instalación al gateway y consultan el cuadro de mando al día siguiente: tres desarrolladores representan el 60 % del gasto en tokens, en los tres casos porque Opus es su modelo por defecto, y una tarea programada reenvía un contexto amplio cada hora. Establecen una directiva de modelos que enruta las ediciones rutinarias a Sonnet, solucionan la tarea y la curva de tendencia cambia su rumbo, sin pedir a nadie que ejecute un comando en su portátil. La observabilidad no modificó el comportamiento; ver los datos sí lo hizo.
El límite honesto: un gateway muestra el gasto y te permite limitarlo. No reescribe prompts; hace que el despilfarro sea imposible de ignorar y te proporciona la palanca de directivas para actuar. El aspecto del cumplimiento se trata en Gobernanza de Claude Code con un AI gateway.
Detalles importantes a tener en cuenta
- La
/usagecifra en dólares es una estimación calculada localmente a precio de catálogo. Si tu organización paga tarifas contratadas, no coincidirá con la factura a menos que un administrador configure la anulación de tarifas. /usagees por máquina. Un desarrollador que programa en un portátil y en un ordenador de sobremesa ve dos imágenes parciales; solo una métrica externa a la máquina (OTel o un gateway) las reconcilia.- Los cuadros de mando de los proveedores cloud fragmentan los datos. En Bedrock, Vertex o Foundry, tu gasto reside en la consola de facturación del cloud, y la atribución por usuario requiere OpenTelemetry o un gateway por encima.
- Las sesiones inactivas siguen generando solicitudes. Las tareas programadas y el trabajo en segundo plano reenvían el contexto completo en su intervalo, por lo que un desarrollador que parece inactivo aún puede generar costes; solo lo verás en una traza por solicitud.
- Contar no es limitar. OpenTelemetry te informa de que se ha rebasado un presupuesto a posteriori; solo un elemento en la ruta de la solicitud puede detenerla antes de que genere gasto.
session.ides una trampa de cardinalidad. Si se deja activada para los cuadros de mando de la flota, crea una serie de métricas por sesión, lo que puede disparar los costes en un backend de observabilidad con tarifa basada en uso; atribuye por usuario en su lugar.- Los equipos de agentes multiplican los tokens. Las ejecuciones multiagente consumen aproximadamente 7 veces más tokens que una sesión individual, por lo que su adopción puede hacer que el gasto se dispare sin que varíe el comportamiento individual.
Lecturas relacionadas
- Observabilidad para Claude en producción: contabilidad de tokens y trazabilidad: la contabilidad de tokens en profundidad
- Seguimiento de costes de Claude Code con el TrueFoundry AI Gateway: la atribución por desarrollador en la práctica
- Centralización del control de costes para IDE de código con IA: una vista única para Claude Code, Cursor y Codex
- Precios de Claude Code explicados: qué cuestan realmente los tokens que estás observando
- Gobernanza de Claude Code con un AI gateway: transformar la observabilidad en aplicación de directivas
Conclusión
La observabilidad de Claude Code es en realidad la observabilidad de costes con el nivel de detalle al máximo: tokens desglosados de cuatro formas, atribuidos a un desarrollador, un modelo y una tarea. Las herramientas nativas responden a esto para una persona en una máquina; OpenTelemetry responde para la flota si instrumentas cada máquina; y un gateway responde para la flota por defecto, porque cada solicitud ya pasa a través de él.
Elige la capa que se adapte al alcance de visibilidad que necesitas. Si la respuesta es "por desarrollador, en todos los modelos y proveedores, con la capacidad de actuar sobre lo que encuentre", la ruta de la solicitud es el lugar donde debes posicionarte.
TrueFoundry AI Gateway ofrece una latencia de entre 3 y 4 ms, gestiona más de 350 RPS en una vCPU, se escala horizontalmente con facilidad y está listo para la producción, mientras que LitellM presenta una latencia alta, tiene dificultades para superar un RPS moderado, carece de escalado integrado y es ideal para cargas de trabajo ligeras o de prototipos.













.webp)

.webp)






