Monitoreo
Aprende cómo habilitar y configurar OpenTelemetry para Claude Code.
Claude Code soporta métricas y eventos de OpenTelemetry (OTel) para monitoreo y observabilidad.
Todas las métricas son datos de series temporales exportados a través del protocolo estándar de métricas de OpenTelemetry, y los eventos son exportados a través del protocolo de logs/eventos de OpenTelemetry. Es responsabilidad del usuario asegurar que sus backends de métricas y logs estén configurados correctamente y que la granularidad de agregación cumpla con sus requisitos de monitoreo.
El soporte de OpenTelemetry está actualmente en beta y los detalles están sujetos a cambios.
Inicio Rápido
Configura OpenTelemetry usando variables de entorno:
Los intervalos de exportación predeterminados son 60 segundos para métricas y 5 segundos para logs. Durante la configuración, es posible que desees usar intervalos más cortos para propósitos de depuración. Recuerda restablecer estos para uso en producción.
Para opciones de configuración completas, consulta la especificación de OpenTelemetry.
Configuración de Administrador
Los administradores pueden configurar las configuraciones de OpenTelemetry para todos los usuarios a través del archivo de configuraciones administradas. Esto permite el control centralizado de las configuraciones de telemetría en toda una organización. Consulta la precedencia de configuraciones para más información sobre cómo se aplican las configuraciones.
El archivo de configuraciones administradas se encuentra en:
- macOS:
/Library/Application Support/ClaudeCode/managed-settings.json
- Linux y WSL:
/etc/claude-code/managed-settings.json
- Windows:
C:\ProgramData\ClaudeCode\managed-settings.json
Ejemplo de configuración de configuraciones administradas:
Las configuraciones administradas pueden ser distribuidas a través de MDM (Mobile Device Management) u otras soluciones de gestión de dispositivos. Las variables de entorno definidas en el archivo de configuraciones administradas tienen alta precedencia y no pueden ser anuladas por los usuarios.
Detalles de Configuración
Variables de Configuración Comunes
Variable de Entorno | Descripción | Valores de Ejemplo |
---|---|---|
CLAUDE_CODE_ENABLE_TELEMETRY | Habilita la recolección de telemetría (requerido) | 1 |
OTEL_METRICS_EXPORTER | Tipo(s) de exportador de métricas (separados por comas) | console , otlp , prometheus |
OTEL_LOGS_EXPORTER | Tipo(s) de exportador de logs/eventos (separados por comas) | console , otlp |
OTEL_EXPORTER_OTLP_PROTOCOL | Protocolo para exportador OTLP (todas las señales) | grpc , http/json , http/protobuf |
OTEL_EXPORTER_OTLP_ENDPOINT | Endpoint del colector OTLP (todas las señales) | http://localhost:4317 |
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL | Protocolo para métricas (anula el general) | grpc , http/json , http/protobuf |
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | Endpoint de métricas OTLP (anula el general) | http://localhost:4318/v1/metrics |
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL | Protocolo para logs (anula el general) | grpc , http/json , http/protobuf |
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT | Endpoint de logs OTLP (anula el general) | http://localhost:4318/v1/logs |
OTEL_EXPORTER_OTLP_HEADERS | Encabezados de autenticación para OTLP | Authorization=Bearer token |
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY | Clave de cliente para autenticación mTLS | Ruta al archivo de clave de cliente |
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE | Certificado de cliente para autenticación mTLS | Ruta al archivo de certificado de cliente |
OTEL_METRIC_EXPORT_INTERVAL | Intervalo de exportación en milisegundos (predeterminado: 60000) | 5000 , 60000 |
OTEL_LOGS_EXPORT_INTERVAL | Intervalo de exportación de logs en milisegundos (predeterminado: 5000) | 1000 , 10000 |
OTEL_LOG_USER_PROMPTS | Habilitar el registro del contenido de prompts del usuario (predeterminado: deshabilitado) | 1 para habilitar |
Control de Cardinalidad de Métricas
Las siguientes variables de entorno controlan qué atributos se incluyen en las métricas para gestionar la cardinalidad:
Variable de Entorno | Descripción | Valor Predeterminado | Ejemplo para Deshabilitar |
---|---|---|---|
OTEL_METRICS_INCLUDE_SESSION_ID | Incluir atributo session.id en métricas | true | false |
OTEL_METRICS_INCLUDE_VERSION | Incluir atributo app.version en métricas | false | true |
OTEL_METRICS_INCLUDE_ACCOUNT_UUID | Incluir atributo user.account_uuid en métricas | true | false |
Estas variables ayudan a controlar la cardinalidad de las métricas, lo que afecta los requisitos de almacenamiento y el rendimiento de consultas en tu backend de métricas. Una cardinalidad más baja generalmente significa mejor rendimiento y menores costos de almacenamiento, pero datos menos granulares para el análisis.
Encabezados Dinámicos
Para entornos empresariales que requieren autenticación dinámica, puedes configurar un script para generar encabezados dinámicamente:
Configuración de Configuraciones
Agrega a tu .claude/settings.json
:
Requisitos del Script
El script debe generar JSON válido con pares clave-valor de cadena que representen encabezados HTTP:
Limitaciones Importantes
Los encabezados se obtienen solo al inicio, no durante el tiempo de ejecución. Esto se debe a las limitaciones de la arquitectura del exportador de OpenTelemetry.
Para escenarios que requieren actualización frecuente de tokens, usa un Colector de OpenTelemetry como proxy que puede actualizar sus propios encabezados.
Soporte para Organizaciones Multi-Equipo
Las organizaciones con múltiples equipos o departamentos pueden agregar atributos personalizados para distinguir entre diferentes grupos usando la variable de entorno OTEL_RESOURCE_ATTRIBUTES
:
Estos atributos personalizados se incluirán en todas las métricas y eventos, permitiéndote:
- Filtrar métricas por equipo o departamento
- Rastrear costos por centro de costos
- Crear dashboards específicos por equipo
- Configurar alertas para equipos específicos
Configuraciones de Ejemplo
Métricas y Eventos Disponibles
Atributos Estándar
Todas las métricas y eventos comparten estos atributos estándar:
Atributo | Descripción | Controlado Por |
---|---|---|
session.id | Identificador único de sesión | OTEL_METRICS_INCLUDE_SESSION_ID (predeterminado: true) |
app.version | Versión actual de Claude Code | OTEL_METRICS_INCLUDE_VERSION (predeterminado: false) |
organization.id | UUID de organización (cuando está autenticado) | Siempre incluido cuando está disponible |
user.account_uuid | UUID de cuenta (cuando está autenticado) | OTEL_METRICS_INCLUDE_ACCOUNT_UUID (predeterminado: true) |
terminal.type | Tipo de terminal (ej., iTerm.app , vscode , cursor , tmux ) | Siempre incluido cuando se detecta |
Métricas
Claude Code exporta las siguientes métricas:
Nombre de Métrica | Descripción | Unidad |
---|---|---|
claude_code.session.count | Conteo de sesiones CLI iniciadas | count |
claude_code.lines_of_code.count | Conteo de líneas de código modificadas | count |
claude_code.pull_request.count | Número de pull requests creados | count |
claude_code.commit.count | Número de commits de git creados | count |
claude_code.cost.usage | Costo de la sesión de Claude Code | USD |
claude_code.token.usage | Número de tokens utilizados | tokens |
claude_code.code_edit_tool.decision | Conteo de decisiones de permisos de herramientas de edición de código | count |
claude_code.active_time.total | Tiempo activo total en segundos | s |
Detalles de Métricas
Contador de Sesión
Se incrementa al inicio de cada sesión.
Atributos:
- Todos los atributos estándar
Contador de Líneas de Código
Se incrementa cuando se agrega o elimina código.
Atributos:
- Todos los atributos estándar
type
: ("added"
,"removed"
)
Contador de Pull Request
Se incrementa al crear pull requests a través de Claude Code.
Atributos:
- Todos los atributos estándar
Contador de Commit
Se incrementa al crear commits de git a través de Claude Code.
Atributos:
- Todos los atributos estándar
Contador de Costo
Se incrementa después de cada solicitud de API.
Atributos:
- Todos los atributos estándar
model
: Identificador del modelo (ej., “claude-3-5-sonnet-20241022”)
Contador de Token
Se incrementa después de cada solicitud de API.
Atributos:
- Todos los atributos estándar
type
: ("input"
,"output"
,"cacheRead"
,"cacheCreation"
)model
: Identificador del modelo (ej., “claude-3-5-sonnet-20241022”)
Contador de Decisión de Herramienta de Edición de Código
Se incrementa cuando el usuario acepta o rechaza el uso de herramientas Edit, MultiEdit, Write, o NotebookEdit.
Atributos:
- Todos los atributos estándar
tool
: Nombre de la herramienta ("Edit"
,"MultiEdit"
,"Write"
,"NotebookEdit"
)decision
: Decisión del usuario ("accept"
,"reject"
)language
: Lenguaje de programación del archivo editado (ej.,"TypeScript"
,"Python"
,"JavaScript"
,"Markdown"
). Devuelve"unknown"
para extensiones de archivo no reconocidas.
Contador de Tiempo Activo
Rastrea el tiempo real gastado usando activamente Claude Code (no tiempo inactivo). Esta métrica se incrementa durante las interacciones del usuario como escribir prompts o recibir respuestas.
Atributos:
- Todos los atributos estándar
Eventos
Claude Code exporta los siguientes eventos a través de logs/eventos de OpenTelemetry (cuando OTEL_LOGS_EXPORTER
está configurado):
Evento de Prompt de Usuario
Se registra cuando un usuario envía un prompt.
Nombre del Evento: claude_code.user_prompt
Atributos:
- Todos los atributos estándar
event.name
:"user_prompt"
event.timestamp
: Marca de tiempo ISO 8601prompt_length
: Longitud del promptprompt
: Contenido del prompt (censurado por defecto, habilitar conOTEL_LOG_USER_PROMPTS=1
)
Evento de Resultado de Herramienta
Se registra cuando una herramienta completa la ejecución.
Nombre del Evento: claude_code.tool_result
Atributos:
- Todos los atributos estándar
event.name
:"tool_result"
event.timestamp
: Marca de tiempo ISO 8601tool_name
: Nombre de la herramientasuccess
:"true"
o"false"
duration_ms
: Tiempo de ejecución en milisegundoserror
: Mensaje de error (si falló)decision
: Ya sea"accept"
o"reject"
source
: Fuente de decisión -"config"
,"user_permanent"
,"user_temporary"
,"user_abort"
, o"user_reject"
tool_parameters
: Cadena JSON que contiene parámetros específicos de la herramienta (cuando está disponible)- Para herramienta Bash: incluye
bash_command
,full_command
,timeout
,description
,sandbox
- Para herramienta Bash: incluye
Evento de Solicitud de API
Se registra para cada solicitud de API a Claude.
Nombre del Evento: claude_code.api_request
Atributos:
- Todos los atributos estándar
event.name
:"api_request"
event.timestamp
: Marca de tiempo ISO 8601model
: Modelo utilizado (ej., “claude-3-5-sonnet-20241022”)cost_usd
: Costo estimado en USDduration_ms
: Duración de la solicitud en milisegundosinput_tokens
: Número de tokens de entradaoutput_tokens
: Número de tokens de salidacache_read_tokens
: Número de tokens leídos del cachécache_creation_tokens
: Número de tokens utilizados para la creación del caché
Evento de Error de API
Se registra cuando una solicitud de API a Claude falla.
Nombre del Evento: claude_code.api_error
Atributos:
- Todos los atributos estándar
event.name
:"api_error"
event.timestamp
: Marca de tiempo ISO 8601model
: Modelo utilizado (ej., “claude-3-5-sonnet-20241022”)error
: Mensaje de errorstatus_code
: Código de estado HTTP (si aplica)duration_ms
: Duración de la solicitud en milisegundosattempt
: Número de intento (para solicitudes reintentadas)
Evento de Decisión de Herramienta
Se registra cuando se toma una decisión de permiso de herramienta (aceptar/rechazar).
Nombre del Evento: claude_code.tool_decision
Atributos:
- Todos los atributos estándar
event.name
:"tool_decision"
event.timestamp
: Marca de tiempo ISO 8601tool_name
: Nombre de la herramienta (ej., “Read”, “Edit”, “MultiEdit”, “Write”, “NotebookEdit”, etc.)decision
: Ya sea"accept"
o"reject"
source
: Fuente de decisión -"config"
,"user_permanent"
,"user_temporary"
,"user_abort"
, o"user_reject"
Interpretando Datos de Métricas y Eventos
Las métricas exportadas por Claude Code proporcionan información valiosa sobre patrones de uso y productividad. Aquí hay algunas visualizaciones y análisis comunes que puedes crear:
Monitoreo de Uso
Métrica | Oportunidad de Análisis |
---|---|
claude_code.token.usage | Desglosar por type (entrada/salida), usuario, equipo, o modelo |
claude_code.session.count | Rastrear adopción y compromiso a lo largo del tiempo |
claude_code.lines_of_code.count | Medir productividad rastreando adiciones/eliminaciones de código |
claude_code.commit.count & claude_code.pull_request.count | Entender el impacto en los flujos de trabajo de desarrollo |
Monitoreo de Costos
La métrica claude_code.cost.usage
ayuda con:
- Rastrear tendencias de uso entre equipos o individuos
- Identificar sesiones de alto uso para optimización
Las métricas de costo son aproximaciones. Para datos oficiales de facturación, consulta tu proveedor de API (Consola de Anthropic, AWS Bedrock, o Google Cloud Vertex).
Alertas y Segmentación
Alertas comunes a considerar:
- Picos de costo
- Consumo inusual de tokens
- Alto volumen de sesiones de usuarios específicos
Todas las métricas pueden ser segmentadas por user.account_uuid
, organization.id
, session.id
, model
, y app.version
.
Análisis de Eventos
Los datos de eventos proporcionan información detallada sobre las interacciones de Claude Code:
Patrones de Uso de Herramientas: Analiza eventos de resultados de herramientas para identificar:
- Herramientas más frecuentemente utilizadas
- Tasas de éxito de herramientas
- Tiempos promedio de ejecución de herramientas
- Patrones de error por tipo de herramienta
Monitoreo de Rendimiento: Rastrea duraciones de solicitudes de API y tiempos de ejecución de herramientas para identificar cuellos de botella de rendimiento.
Consideraciones de Backend
Tu elección de backends de métricas y logs determinará los tipos de análisis que puedes realizar:
Para Métricas:
- Bases de datos de series temporales (ej., Prometheus): Cálculos de tasa, métricas agregadas
- Almacenes columnares (ej., ClickHouse): Consultas complejas, análisis de usuarios únicos
- Plataformas de observabilidad completas (ej., Honeycomb, Datadog): Consultas avanzadas, visualización, alertas
Para Eventos/Logs:
- Sistemas de agregación de logs (ej., Elasticsearch, Loki): Búsqueda de texto completo, análisis de logs
- Almacenes columnares (ej., ClickHouse): Análisis de eventos estructurados
- Plataformas de observabilidad completas (ej., Honeycomb, Datadog): Correlación entre métricas y eventos
Para organizaciones que requieren métricas de Usuarios Activos Diarios/Semanales/Mensuales (DAU/WAU/MAU), considera backends que soporten consultas eficientes de valores únicos.
Información del Servicio
Todas las métricas y eventos se exportan con los siguientes atributos de recurso:
service.name
:claude-code
service.version
: Versión actual de Claude Codeos.type
: Tipo de sistema operativo (ej.,linux
,darwin
,windows
)os.version
: Cadena de versión del sistema operativohost.arch
: Arquitectura del host (ej.,amd64
,arm64
)wsl.version
: Número de versión de WSL (solo presente cuando se ejecuta en Windows Subsystem for Linux)- Nombre del Medidor:
com.anthropic.claude_code
Recursos de Medición de ROI
Para una guía completa sobre la medición del retorno de inversión para Claude Code, incluyendo configuración de telemetría, análisis de costos, métricas de productividad, y reportes automatizados, consulta la Guía de Medición de ROI de Claude Code. Este repositorio proporciona configuraciones de Docker Compose listas para usar, configuraciones de Prometheus y OpenTelemetry, y plantillas para generar reportes de productividad integrados con herramientas como Linear.
Consideraciones de Seguridad/Privacidad
- La telemetría es opcional y requiere configuración explícita
- Información sensible como claves de API o contenidos de archivos nunca se incluyen en métricas o eventos
- El contenido de prompts de usuario está censurado por defecto - solo se registra la longitud del prompt. Para habilitar el registro de prompts de usuario, establece
OTEL_LOG_USER_PROMPTS=1