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 se exportan 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:

# 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

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: /etc/claude-code/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"
  }
}

Las configuraciones administradas pueden distribuirse 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 EntornoDescripciónValores de Ejemplo
CLAUDE_CODE_ENABLE_TELEMETRYHabilita la recolección de telemetría (requerido)1
OTEL_METRICS_EXPORTERTipo(s) de exportador de métricas (separados por comas)console, otlp, prometheus
OTEL_LOGS_EXPORTERTipo(s) de exportador de logs/eventos (separados por comas)console, otlp
OTEL_EXPORTER_OTLP_PROTOCOLProtocolo para exportador OTLP (todas las señales)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINTEndpoint del colector OTLP (todas las señales)http://localhost:4317
OTEL_EXPORTER_OTLP_METRICS_PROTOCOLProtocolo para métricas (anula el general)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_METRICS_ENDPOINTEndpoint de métricas OTLP (anula el general)http://localhost:4318/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_PROTOCOLProtocolo para logs (anula el general)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTEndpoint de logs OTLP (anula el general)http://localhost:4318/v1/logs
OTEL_EXPORTER_OTLP_HEADERSHeaders de autenticación para OTLPAuthorization=Bearer token
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEYClave de cliente para autenticación mTLSRuta al archivo de clave de cliente
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATECertificado de cliente para autenticación mTLSRuta al archivo de certificado de cliente
OTEL_METRIC_EXPORT_INTERVALIntervalo de exportación en milisegundos (predeterminado: 60000)5000, 60000
OTEL_LOGS_EXPORT_INTERVALIntervalo de exportación de logs en milisegundos (predeterminado: 5000)1000, 10000
OTEL_LOG_USER_PROMPTSHabilitar logging del contenido de prompts de 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 EntornoDescripciónValor PredeterminadoEjemplo para Deshabilitar
OTEL_METRICS_INCLUDE_SESSION_IDIncluir atributo session.id en métricastruefalse
OTEL_METRICS_INCLUDE_VERSIONIncluir atributo app.version en métricasfalsetrue
OTEL_METRICS_INCLUDE_ACCOUNT_UUIDIncluir atributo user.account_uuid en métricastruefalse

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 análisis.

​
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

​
Configuraciones de Ejemplo

# Depuración en 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:

AtributoDescripciónControlado Por
session.idIdentificador único de sesiónOTEL_METRICS_INCLUDE_SESSION_ID (predeterminado: true)
app.versionVersión actual de Claude CodeOTEL_METRICS_INCLUDE_VERSION (predeterminado: false)
organization.idUUID de organización (cuando está autenticado)Siempre incluido cuando está disponible
user.account_uuidUUID de cuenta (cuando está autenticado)OTEL_METRICS_INCLUDE_ACCOUNT_UUID (predeterminado: true)
terminal.typeTipo 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étricaDescripciónUnidad
claude_code.session.countConteo de sesiones CLI iniciadascount
claude_code.lines_of_code.countConteo de líneas de código modificadascount
claude_code.pull_request.countNúmero de pull requests creadoscount
claude_code.commit.countNúmero de commits de git creadoscount
claude_code.cost.usageCosto de la sesión de Claude CodeUSD
claude_code.token.usageNúmero de tokens utilizadostokens
claude_code.code_edit_tool.decisionConteo de decisiones de permisos de herramientas de edición de códigocount

​
Detalles de Métricas

​
Contador de Sesión

Se incrementa al inicio de cada sesión.

Atributos:

​
Contador de Líneas de Código

Se incrementa cuando se agrega o elimina código.

Atributos:

​
Contador de Pull Request

Se incrementa al crear pull requests a través de Claude Code.

Atributos:

​
Contador de Commit

Se incrementa al crear commits de git a través de Claude Code.

Atributos:

​
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.

​
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
  • name: Nombre de la herramienta
  • success: "true" o "false"
  • duration_ms: Tiempo de ejecución en milisegundos
  • error: Mensaje de error (si falló)

​
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

MétricaOportunidad de Análisis
claude_code.token.usageDesglosar por type (entrada/salida), usuario, equipo, o modelo
claude_code.session.countRastrear adopción y compromiso a lo largo del tiempo
claude_code.lines_of_code.countMedir productividad rastreando adiciones/eliminaciones de código
claude_code.commit.count & claude_code.pull_request.countEntender impacto en 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 (Anthropic Console, 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 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 se exportan con:

  • Nombre del Servicio: claude-code
  • Versión del Servicio: Versión actual de Claude Code
  • Nombre del Medidor: com.anthropic.claude_code

​
Consideraciones de Seguridad/Privacidad

  • La telemetría es opt-in y requ