Monitoreo de costos, atribución y controles de gasto

Módulo 7 · Administración y medición · Lección 6 de 6

Al terminar esta lección podrás identificar las tres capas de visibilidad del gasto, explicar cómo la métrica cost.usage permite la atribución por equipo y configurar límites de gasto mediante la Admin API.

El costo sin atribución es solo un número.

Capas de visibilidad

Tres superficies. Cada una responde a una pregunta de gasto distinta.

La visibilidad del costo en un engagement de Claude Code no proviene de un único dashboard. Tres superficies cubren casos de uso distintos, y la adecuada depende de si el cliente necesita una vista general, una consulta programática o la atribución por equipo en un SIEM.

En la práctica, la mayoría de los clientes usan las tres: el dashboard de administración para el seguimiento diario, la Analytics API para construir informes internos de costos y la métrica cost.usage de OTel para la atribución de cargos (charge-back) entre equipos.

Capa	Superficie	Qué ofrece	Notas
01	Dashboard de administración	Vista visual general del gasto por modelo y funcionalidad (Spend by model and feature) en Organization settings. Se actualiza a diario y no requiere acceso a la API.	Útil para directivos que necesitan una vista de resumen. No sirve para informes programáticos ni para desgloses por equipo.
02	Analytics API	Interfaz programática con gasto y uso agregados por workspace. Snapshots diarios. Permite consultar por rango de fechas y exportar para herramientas de BI. Cubre todo el uso de Claude, no solo el de Claude Code.	Requiere una clave de API de administrador.
03	Métrica claude_code.cost.usage de OTel	Gasto en USD por sesión dentro del flujo de OTel. Es la única superficie que admite atribución por equipo mediante las etiquetas de OTEL_RESOURCE_ATTRIBUTES. Es en tiempo real, no por lotes.	Se profundiza en el tema 2 de esta lección.

La métrica cost.usage

La métrica que hace posible el charge-back.

claude_code.cost.usage reporta el gasto estimado en USD por sesión de Claude Code, etiquetado con los atributos que hacen posible el informe por equipo. Es la superficie de atribución que ninguna otra capa de visibilidad ofrece.

1. Qué mide

claude_code.cost.usage emite un valor acumulado de gasto en USD al final de cada sesión de Claude Code. Se acumula a lo largo de las solicitudes de API de esa sesión y refleja el costo de los tokens de entrada, los tokens de salida, las lecturas de caché y la creación de caché.

La métrica complementaria. claude_code.token.usage desglosa el gasto en recuentos de tokens por tipo (input, output, cacheRead y cacheCreation), todos etiquetados con el mismo modelo y las mismas etiquetas de equipo que la métrica de costo. Usa token.usage cuando el cliente necesite entender la composición de su costo, no solo el total. Las proporciones entre lectura y creación de caché indican si el diseño de las sesiones es eficiente.

La métrica se emite por sesión, no por solicitud. Una sesión larga se acumula mientras se ejecuta. Consulta en el SIEM el total de la sesión, no los puntos de datos individuales, al construir informes de costo.

2. Atributos de atribución

Cada punto de datos de cost.usage lleva un conjunto de atributos integrados, además de las etiquetas personalizadas que se aplican mediante OTEL_RESOURCE_ATTRIBUTES. Esta combinación es lo que hace posible el charge-back por equipo y por proyecto.

Atributos integrados en cada punto de datos:

• model: qué modelo de Claude se usó (por ejemplo, claude-sonnet-4-6)
• query_source: de dónde se originó la solicitud: human, subtask o tool_use
• agent.name, skill.name, plugin.name, mcp_server.name, mcp_tool.name: cuando la sesión usó estas funcionalidades, el nombre correspondiente se etiqueta automáticamente

Etiquetas personalizadas mediante MDM:

• Define OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123" en el archivo de managed settings para añadir etiquetas definidas por la organización a cada métrica de los dispositivos en ese ámbito.
• Despliega valores de atributos distintos por equipo delimitando el perfil MDM. Todas las métricas de un desarrollador del equipo Platform llevan automáticamente team.id=platform.

Los atributos personalizados son aditivos. No reemplazan a los integrados. Un punto de datos llevará a la vez la etiqueta del modelo y tu etiqueta personalizada cost_center.

3. Advertencia de aproximación

La métrica cost.usage reporta gasto estimado. Es una aproximación del lado del cliente basada en el precio publicado de cada modelo aplicado a los recuentos de tokens. La cifra de facturación autoritativa proviene del proveedor de API: Anthropic Console, Amazon Bedrock o Google Vertex.

En la práctica:

• Usa la métrica de costo de OTel para la asignación de cargos, el presupuesto por equipo y el seguimiento de tendencias.
• Usa el panel de facturación del proveedor de API para el número real de la factura. Nunca presentes la cifra de OTel como el importe facturable ante un equipo financiero.
• La variación suele ser pequeña, pero puede aparecer durante cambios de precios de los modelos o cuando cambia el comportamiento de la caché. Reconcilia con la facturación oficial cada trimestre.

Esta advertencia debe aparecer en cada briefing de costos para el cliente. Evita una discrepancia entre la cifra de “gasto por equipo” que informa el SIEM y la línea de la factura.

flowchart LR
    M["cost.usage de OTel (estimación del lado del cliente)"] --> T["Asignación por equipo y seguimiento de tendencias"]
    F["Factura del proveedor de API (cifra autoritativa)"] --> RC["Reconciliación trimestral"]
    M --> RC

Controles de gasto

Límites, etiquetas, alertas y la única advertencia que debes llevar contigo.

Cuatro decisiones que surgen en casi todas las conversaciones sobre costos y gobernanza. La tabla describe cómo implementar cada una.

Control	Estado	Cómo implementarlo
Límites de gasto mediante la Admin API (Budget enforcement)	Disponible ahora	El endpoint /organizations/{id}/spend-limits establece límites mensuales máximos por workspace. Cuando un workspace alcanza su límite, las solicitudes de Claude Code fallan de forma controlada hasta que se restablezca el tope o se eleve. Establece límites por workspace de equipo, no a nivel de organización, para un control granular.
Charge-back por equipo (Charge-back setup)	Mediante configuración MDM	Define OTEL_RESOURCE_ATTRIBUTES por ámbito de equipo en el perfil de managed-settings. Todas las métricas de los dispositivos de ese ámbito llevan la etiqueta del equipo. Construye un dashboard en el SIEM que agrupe cost.usage por esa etiqueta. Es la arquitectura de charge-back para despliegues multiequipo.
Alertas de gasto (Spend alert design)	Requiere OTel	Crea una regla en el SIEM sobre claude_code.cost.usage que se dispare cuando el total acumulado diario o semanal de una etiqueta de equipo supere un umbral. Combínala con una alerta por Slack o correo. Es proactiva; el límite de gasto de la Admin API es el tope definitivo cuando la alerta no basta.
Nota para finanzas (OTel cost is an estimate)	Informar siempre	cost.usage es una aproximación del lado del cliente, no la cifra de facturación. Úsala para la asignación por equipo y el seguimiento de tendencias. Para la factura real, indica a finanzas el proveedor de API: Anthropic Console, la facturación de AWS Bedrock o la facturación de GCP Vertex. Reconcilia cada trimestre.

La alerta proactiva y el límite de gasto funcionan en secuencia: la alerta avisa antes, y el límite de la Admin API actúa como tope cuando la alerta no es suficiente.

flowchart LR
    S1["Regla SIEM sobre cost.usage por etiqueta de equipo"] --> S2["Alerta por Slack o correo al superar el umbral"]
    S2 --> S3["Límite de gasto en la Admin API (tope definitivo por workspace)"]

Comprueba tu comprensión

Escenario · Decisiones de arquitectura de costos

Un CTO, un equipo financiero y un equipo de seguridad quieren cosas distintas de los datos de costo. Seis puntos en total. Cada parte interesada tiene una solicitud específica: la superficie equivocada no tiene la granularidad necesaria o informa la cifra incorrecta. Cada opción vale 2 puntos (mejor), 1 (parcial) o 0 (incorrecta). Elige una opción en cada decisión y compara tu criterio con la explicación.

Decisión 1 de 3 · Visibilidad ejecutiva

El CTO quiere un resumen mensual del gasto para compartirlo en la revisión de liderazgo. No necesita desglose por equipo, solo el gasto total por modelo. ¿Qué superficie encaja?

• A. Construir un dashboard a partir del flujo de la métrica cost.usage de OTel
• B. Dirigir al CTO al dashboard de administración en Organization settings
• C. Obtener un informe del panel de facturación de la consola del proveedor de API

Ver respuesta

Mejor opción: B (2 puntos). Parcial: A (1 punto). Incorrecta: C (0 puntos).

A. Construir un dashboard a partir del flujo de la métrica cost.usage de OTel (parcial, 1 punto). El SIEM recibe cost.usage en tiempo real. Construye un dashboard que agrupe el gasto total por modelo durante el mes.

Retroalimentación: Construir un dashboard en el SIEM a partir de cost.usage funciona y ofrece más granularidad, pero está sobrediseñado para un CTO que necesita un resumen mensual. El dashboard de administración ofrece esto sin configuración adicional.

B. Dirigir al CTO al dashboard de administración en Organization settings (mejor, 2 puntos). El dashboard de administración muestra Spend by model and feature como vista visual general. Se actualiza a diario y no requiere configuración adicional. Cualquier Owner puede compartir una captura o exportar la vista.

Retroalimentación: Correcto. El dashboard de administración es la opción adecuada aquí: una vista visual por modelo y funcionalidad, actualizada a diario y accesible para cualquier Owner sin configuración adicional. El dashboard de OTel funciona, pero requiere una infraestructura que el CTO no necesita para una vista de resumen.

C. Obtener un informe del panel de facturación de la consola del proveedor de API (incorrecta, 0 puntos). La consola de Anthropic o el panel de facturación de AWS Bedrock muestran el gasto facturado real por modelo. Es la fuente autoritativa.

Retroalimentación: La consola del proveedor de API es la fuente de facturación autoritativa, pero no es la primera herramienta que se muestra a un CTO. Requiere acceso a la plataforma del proveedor, no está alojada dentro de la experiencia de administración de Claude y muestra datos de facturación, no la vista “Spend by model and feature” que ofrece la configuración de la organización.

Decisión 2 de 3 · Charge-back para finanzas

Finanzas quiere cargar el gasto de Claude Code a los ocho equipos de ingeniería que lo usan. Necesitan una cifra mensual por equipo. ¿Qué configuras?

• A. Crear ocho workspaces y extraer el gasto por workspace desde la Analytics API
• B. Desplegar OTEL_RESOURCE_ATTRIBUTES con etiquetas de equipo mediante MDM y construir una consulta en el SIEM sobre cost.usage
• C. Exportar los registros de auditoría mensuales y calcular el gasto por equipo a partir de los eventos de inicio de sesión

Ver respuesta

Mejor opción: B (2 puntos). Parcial: C (1 punto). Incorrecta: A (0 puntos).

A. Crear ocho workspaces y extraer el gasto por workspace desde la Analytics API (incorrecta, 0 puntos). La Analytics API devuelve el gasto por workspace. Ocho workspaces, uno por equipo, producirían ocho cifras de costo para compartir con finanzas.

Retroalimentación: Ocho workspaces separados funciona en principio. La Analytics API sí devuelve el gasto por workspace. Pero tiene mucha sobrecarga: ocho políticas de workspace que gestionar, ocho consultas a la API que ejecutar y ninguna visibilidad en tiempo real. El enfoque de etiquetas por MDM escala mejor.

B. Desplegar OTEL_RESOURCE_ATTRIBUTES con etiquetas de equipo mediante MDM y construir una consulta en el SIEM sobre cost.usage (mejor, 2 puntos). El perfil de managed-settings de cada equipo recibe una etiqueta team.id. El SIEM agrupa cost.usage por team.id y exporta un total mensual por equipo para finanzas.

Retroalimentación: Correcto. OTEL_RESOURCE_ATTRIBUTES con etiquetas de equipo mediante MDM es la arquitectura de charge-back para despliegues multiequipo. Etiqueta cada punto de datos de cost.usage en origen, sin requerir ocho workspaces separados ni cruces manuales.

C. Exportar los registros de auditoría mensuales y calcular el gasto por equipo a partir de los eventos de inicio de sesión (parcial, 1 punto). Los registros de auditoría muestran qué usuarios estuvieron activos. Cruza la pertenencia de cada usuario a su equipo con el total del dashboard de administración para estimar el gasto por equipo.

Retroalimentación: Los registros de auditoría no contienen datos de gasto. Cruzar la actividad de inicio de sesión con una cifra total de gasto para obtener estimaciones por equipo es frágil e inexacto. No resiste una conciliación con finanzas.

Decisión 3 de 3 · Discrepancia en la conciliación

El equipo financiero señala que la cifra mensual del SIEM es un 3% inferior a la factura de Anthropic Console. ¿Qué les respondes?

• A. Escalar: es posible que el pipeline de OTel haya perdido eventos
• B. Explicar que la cifra de OTel es una estimación; la factura de Console es la cifra de facturación autoritativa
• C. Cambiar a finanzas a la Analytics API para los informes de gasto

Ver respuesta

Mejor opción: B (2 puntos). Parcial: C (1 punto). Incorrecta: A (0 puntos).

A. Escalar: es posible que el pipeline de OTel haya perdido eventos (incorrecta, 0 puntos). Una diferencia del 3% sugiere que se perdieron eventos de OTel en tránsito. Revisa el SIEM buscando huecos en la serie temporal de eventos e investiga la configuración del exportador.

Retroalimentación: Una diferencia del 3% entre una estimación y una factura es un comportamiento esperado, no un evento que escalar. La métrica de costo de OTel está documentada explícitamente como una aproximación. Tratarlo como un fallo del pipeline provocaría una investigación innecesaria.

B. Explicar que la cifra de OTel es una estimación; la factura de Console es la cifra de facturación autoritativa (mejor, 2 puntos). Usa la métrica de costo de OTel para la asignación por equipo. Para el importe real de la factura, referencia siempre la consola de facturación del proveedor de API. Reconcilia cada trimestre y considera las pequeñas variaciones como esperables.

Retroalimentación: Correcto. La métrica cost.usage es una aproximación del lado del cliente, no un registro de facturación. Una variación del 3% entre la cifra de OTel y la factura de Console es normal. Finanzas debe usar la factura de Console para los pagos reales y la métrica de OTel solo para la asignación por equipo.

C. Cambiar a finanzas a la Analytics API para los informes de gasto (parcial, 1 punto). La Analytics API ofrece datos de gasto agregados directamente desde la plataforma. Debería alinearse más con la cifra de facturación de Console que con la estimación de OTel.

Retroalimentación: Cambiar a finanzas a la Analytics API es una mejora razonable, pero no aborda la causa raíz. La Analytics API está más cerca de la fuente de facturación que OTel, pero la respuesta correcta es ser explícito sobre qué superficie es el registro de facturación y cuál es la herramienta de asignación.

Ver debrief y texto de cierre

La fuente asigna un texto de cierre según la puntuación final, sobre un máximo de 6 puntos.

Arquitecto de costos (5 o 6 puntos). Relacionaste cada parte interesada con la superficie correcta y entendiste el límite de la aproximación. La distinción entre herramienta de asignación y registro de facturación es la que más importa en los engagements con clientes, y la manejaste bien.

Base sólida, un error de criterio (3 o 4 puntos). Dos de tres es un buen comienzo. La decisión fallida probablemente mezcló la superficie correcta con el caso de uso correcto. Las tarjetas del tema 3 y el desglose de tres pilares del tema 1 cubren el panorama completo.

Conviene revisar los temas 1 y 2 (0 a 2 puntos). El patrón en el que anclarse: el dashboard de administración para las vistas ejecutivas, OTel cost.usage con etiquetas de atributos de recurso para el charge-back por equipo y la consola del proveedor de API para la factura real. Cada superficie tiene su carril.

Artefacto del curso · Aporte de la lección 6

OTel Configuration + Dashboard Spec

Has recorrido todas las capas de la pila de observabilidad de Claude Code. Este aporte añade la capa de costos a tu especificación de dashboard y completa el artefacto: un bloque de configuración de OTel y una especificación de dashboard de cuatro paneles, listos para entregar al responsable de DevOps del cliente.

1. Añade el panel de atribución de costos a tu especificación de dashboard: cost.usage por equipo y por semana, con model y query_source como atributos secundarios. Es el panel que impulsa la conversación de charge-back.
2. Define el umbral de alerta de gasto para tu cliente: el tope mensual por usuario que debe disparar una notificación antes de que llegue la factura. Indica si lo configurarás mediante la Admin API o desde la Admin Console.
3. Revisa tu artefacto completo: el bloque de configuración de OTel más cuatro paneles del dashboard (sesiones, desarrolladores activos, volumen de tokens por modelo y costo por equipo). Es lo que llevas al traspaso de DevOps del día 1.

Práctica

Has construido una visión completa de cómo se observan, gobiernan y controlan los despliegues de Claude Code. Para llevarlo a la práctica, configura Claude Code en tres entornos (CLI local, IDE y dev container) y ejecuta un script headless de extremo a extremo en cada uno. Comparar la salida de los tres es la forma de familiarizarte con los patrones de instrumentación antes de configurarlos para un cliente.

Ideas clave

Ya puedes ver toda la operación.

Con este capítulo se completa el módulo de administración y medición. A lo largo del módulo has visto cómo se observa, se gobierna y se controla un despliegue de Claude Code. Son las superficies por las que preguntarán tus clientes en cada engagement, y ya sabes qué pregunta corresponde a cada una:

• OTel para los eventos de ejecución.
• Compliance API para la supervisión de las conversaciones.
• Registros de auditoría para la gobernanza administrativa.
• Atribución de costos para finanzas y charge-back.

Siguiente curso: Metodología de entrega. Recorre el arco completo de una activación de Claude Code: definir el alcance del engagement, ejecutar un piloto productivo, gestionar el despliegue y estructurar el traspaso para que el cliente siga avanzando una vez cerrado el engagement.

Siguiente: Identificación y calificación de casos de uso