Monitoreo

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.

​

Inicio Rápido

Configura OpenTelemetry usando variables de entorno:

# 1. Habilitar telemetría
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Elegir exportadores (ambos son opcionales - configura solo lo que necesites)
export OTEL_METRICS_EXPORTER=otlp       # Opciones: otlp, prometheus, console
export OTEL_LOGS_EXPORTER=otlp          # Opciones: otlp, console

# 3. Configurar endpoint OTLP (para exportador OTLP)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. Establecer autenticación (si es requerida)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. Para depuración: reducir intervalos de exportación
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 segundos (predeterminado: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 segundos (predeterminado: 5000ms)

# 6. Ejecutar Claude Code
claude

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 un 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:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.company.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer company-token"
  }
}

​

Detalles de Configuración

​

Variables de Configuración Comunes

​

Control de Cardinalidad de Métricas

Las siguientes variables de entorno controlan qué atributos se incluyen en las métricas para gestionar la cardinalidad:

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:

{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}

​

Requisitos del Script

El script debe generar JSON válido con pares clave-valor de cadena que representen encabezados HTTP:

#!/bin/bash
# Ejemplo: Múltiples encabezados
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

​

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 pueda 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:

# Agregar atributos personalizados para identificación de equipo
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

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

# ❌ Inválido - contiene espacios
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

# ✅ Válido - usa guiones bajos o camelCase en su lugar
export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

# ✅ Válido - codifica por porcentaje caracteres especiales si es necesario
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

​

Configuraciones de Ejemplo

# Depuración de consola (intervalos de 1 segundo)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

# OTLP/gRPC
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Prometheus
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

# Múltiples exportadores
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

# Diferentes endpoints/backends para métricas y logs
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.company.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.company.com:4317

# Solo métricas (sin eventos/logs)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Solo eventos/logs (sin métricas)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

​

Métricas y Eventos Disponibles

​

Atributos Estándar

Todas las métricas y eventos comparten estos atributos estándar:

​

Métricas

Claude Code exporta las siguientes métricas:

​

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 8601
• prompt_length: Longitud del prompt
• prompt: Contenido del prompt (redactado por defecto, habilitar con OTEL_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 8601
• tool_name: Nombre de la herramienta
• success: "true" o "false"
• duration_ms: Tiempo de ejecución en milisegundos
• error: 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

​

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 8601
• model: Modelo utilizado (ej., “claude-3-5-sonnet-20241022”)
• cost_usd: Costo estimado en USD
• duration_ms: Duración de la solicitud en milisegundos
• input_tokens: Número de tokens de entrada
• output_tokens: Número de tokens de salida
• cache_read_tokens: Número de tokens leídos del caché
• cache_creation_tokens: Número de tokens utilizados para creación de 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 8601
• model: Modelo utilizado (ej., “claude-3-5-sonnet-20241022”)
• error: Mensaje de error
• status_code: Código de estado HTTP (si aplica)
• duration_ms: Duración de la solicitud en milisegundos
• attempt: 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 8601
• tool_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

​

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

​

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 segmentarse 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 Code
• os.type: Tipo de sistema operativo (ej., linux, darwin, windows)
• os.version: Cadena de versión del sistema operativo
• host.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 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á redactado por defecto - solo se registra la longitud del prompt. Para habilitar el registro de prompts de usuario, establece OTEL_LOG_USER_PROMPTS=1