​

OpenTelemetry en Claude Code

Claude Code admite métricas de OpenTelemetry (OTel) para monitoreo y observabilidad. Este documento explica cómo habilitar y configurar OTel para Claude Code.

Todas las métricas son datos de series temporales exportados a través del protocolo estándar de métricas de OpenTelemetry. Es responsabilidad del usuario asegurarse de que su backend de métricas esté configurado 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 un exportador
export OTEL_METRICS_EXPORTER=otlp       # Opciones: otlp, prometheus, console

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

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

# 5. Para depuración: reducir el intervalo de exportación (predeterminado: 600000ms/10min)
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 segundos

# 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 los ajustes de OpenTelemetry para todos los usuarios a través del archivo de configuración administrada. Esto permite un control centralizado de la configuración de telemetría en toda una organización. Consulta la jerarquía de configuración para obtener más información sobre cómo se aplican los ajustes.

El archivo de configuración administrada se encuentra en:

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux: /etc/claude-code/managed-settings.json

Ejemplo de configuración de ajustes administrados:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_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 las 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.

​

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

​

Métricas disponibles

Claude Code exporta las siguientes métricas:

​

Detalles de métricas

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

• session.id: Identificador único de sesión (controlado por OTEL_METRICS_INCLUDE_SESSION_ID)
• app.version: Versión actual de Claude Code (controlado por OTEL_METRICS_INCLUDE_VERSION)
• organization.id: UUID de la organización (cuando está autenticado)
• user.account_uuid: UUID de la cuenta (cuando está autenticado, controlado por OTEL_METRICS_INCLUDE_ACCOUNT_UUID)

​

1. Contador de sesiones

Emitido al inicio de cada sesión.

​

2. Contador de líneas de código

Emitido cuando se agrega o elimina código.

• Atributo adicional: type ("added" o "removed")

​

3. Contador de Pull Requests

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

​

4. Contador de Commits

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

​

5. Contador de costos

Emitido después de cada solicitud de API.

• Atributo adicional: model

​

6. Contador de tokens

Emitido después de cada solicitud de API.

• Atributos adicionales: type ("input", "output", "cacheRead", "cacheCreation") y model

​

Interpretación de datos de métricas

Estas métricas proporcionan información sobre patrones de uso, productividad y costos:

​

Monitoreo de uso

​

Monitoreo de costos

La métrica claude_code.cost.usage ayuda con:

• Seguimiento de tendencias de uso entre equipos o individuos
• Identificación de 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.

​

Consideraciones de backend

Para métricas DAU/WAU/MAU, elige backends que admitan consultas eficientes de valores únicos.

​

Información de 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

• La telemetría es opcional y requiere configuración explícita
• La información sensible como claves API o contenidos de archivos nunca se incluyen en las métricas