​

OpenTelemetry dans Claude Code

Claude Code prend en charge les métriques OpenTelemetry (OTel) pour la surveillance et l’observabilité. Ce document explique comment activer et configurer OTel pour Claude Code.

Toutes les métriques sont des données de séries temporelles exportées via le protocole standard de métriques d’OpenTelemetry. Il incombe à l’utilisateur de s’assurer que son backend de métriques est correctement configuré et que la granularité d’agrégation répond à ses exigences de surveillance.

​

Démarrage rapide

Configurez OpenTelemetry à l’aide de variables d’environnement :

# 1. Activer la télémétrie
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Choisir un exportateur
export OTEL_METRICS_EXPORTER=otlp       # Options : otlp, prometheus, console

# 3. Configurer le point de terminaison OTLP (pour l'exportateur OTLP)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. Définir l'authentification (si nécessaire)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. Pour le débogage : réduire l'intervalle d'exportation (par défaut : 600000ms/10min)
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 secondes

# 6. Exécuter Claude Code
claude

Pour les options de configuration complètes, consultez la spécification OpenTelemetry.

​

Configuration administrateur

Les administrateurs peuvent configurer les paramètres OpenTelemetry pour tous les utilisateurs via le fichier de paramètres gérés. Cela permet un contrôle centralisé des paramètres de télémétrie dans toute une organisation. Consultez la hiérarchie de configuration pour plus d’informations sur la façon dont les paramètres sont appliqués.

Le fichier de paramètres gérés se trouve à :

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

Exemple de configuration des paramètres gérés :

{
  "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"
  }
}

​

Détails de configuration

​

Variables de configuration courantes

​

Contrôle de cardinalité des métriques

Les variables d’environnement suivantes contrôlent quels attributs sont inclus dans les métriques pour gérer la cardinalité :

Ces variables aident à contrôler la cardinalité des métriques, ce qui affecte les besoins en stockage et les performances des requêtes dans votre backend de métriques. Une cardinalité plus faible signifie généralement de meilleures performances et des coûts de stockage inférieurs, mais des données moins granulaires pour l’analyse.

​

Exemples de configurations

# Débogage console (intervalles d'1 seconde)
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

# Exportateurs multiples
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

​

Métriques disponibles

Claude Code exporte les métriques suivantes :

​

Détails des métriques

Toutes les métriques partagent ces attributs standard :

• session.id : Identifiant unique de session (contrôlé par OTEL_METRICS_INCLUDE_SESSION_ID)
• app.version : Version actuelle de Claude Code (contrôlée par OTEL_METRICS_INCLUDE_VERSION)
• organization.id : UUID de l’organisation (lorsqu’authentifié)
• user.account_uuid : UUID du compte (lorsqu’authentifié, contrôlé par OTEL_METRICS_INCLUDE_ACCOUNT_UUID)

​

1. Compteur de sessions

Émis au début de chaque session.

​

2. Compteur de lignes de code

Émis lorsque du code est ajouté ou supprimé.

• Attribut supplémentaire : type ("added" ou "removed")

​

3. Compteur de pull requests

Émis lors de la création de pull requests via Claude Code.

​

4. Compteur de commits

Émis lors de la création de commits git via Claude Code.

​

5. Compteur de coûts

Émis après chaque requête API.

• Attribut supplémentaire : model

​

6. Compteur de tokens

Émis après chaque requête API.

• Attributs supplémentaires : type ("input", "output", "cacheRead", "cacheCreation") et model

​

Interprétation des données métriques

Ces métriques fournissent des informations sur les modèles d’utilisation, la productivité et les coûts :

​

Surveillance de l’utilisation

​

Surveillance des coûts

La métrique claude_code.cost.usage aide à :

• Suivre les tendances d’utilisation entre les équipes ou les individus
• Identifier les sessions à forte utilisation pour optimisation

​

Alertes et segmentation

Alertes courantes à considérer :

• Pics de coûts
• Consommation inhabituelle de tokens
• Volume élevé de sessions provenant d’utilisateurs spécifiques

Toutes les métriques peuvent être segmentées par user.account_uuid, organization.id, session.id, model et app.version.

​

Considérations sur le backend

Pour les métriques DAU/WAU/MAU, choisissez des backends qui prennent en charge les requêtes efficaces de valeurs uniques.

​

Informations de service

Toutes les métriques sont exportées avec :

• Nom du service : claude-code
• Version du service : Version actuelle de Claude Code
• Nom du compteur : com.anthropic.claude_code

​

Considérations de sécurité

• La télémétrie est optionnelle et nécessite une configuration explicite
• Les informations sensibles comme les clés API ou le contenu des fichiers ne sont jamais incluses dans les métriques