Claude Code prend en charge les métriques et événements OpenTelemetry (OTel) pour la surveillance et l’observabilité. Toutes les métriques sont des données de séries chronologiques exportées via le protocole de métriques standard d’OpenTelemetry, et les événements sont exportés via le protocole de journaux/événements d’OpenTelemetry. Il est de la responsabilité de l’utilisateur de s’assurer que ses backends de métriques et de journaux sont correctement configurés et que la granularité d’agrégation répond à ses exigences de surveillance.
Le support d’OpenTelemetry est actuellement en version bêta et les détails sont sujets à modification.

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 les exportateurs (les deux sont optionnels - configurez uniquement ce dont vous avez besoin)
export OTEL_METRICS_EXPORTER=otlp       # Options : otlp, prometheus, console
export OTEL_LOGS_EXPORTER=otlp          # Options : otlp, 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 les intervalles d'export
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 secondes (par défaut : 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 secondes (par défaut : 5000ms)

# 6. Exécuter Claude Code
claude
Les intervalles d’export par défaut sont de 60 secondes pour les métriques et de 5 secondes pour les journaux. Lors de la configuration, vous pouvez utiliser des intervalles plus courts à des fins de débogage. N’oubliez pas de les réinitialiser pour une utilisation en production.
Pour les options de configuration complètes, consultez la spécification OpenTelemetry.

Configuration de l’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 précédence des paramètres pour plus d’informations sur la façon dont les paramètres sont appliqués. Le fichier de paramètres gérés est situé à :
  • macOS : /Library/Application Support/ClaudeCode/managed-settings.json
  • Linux et WSL : /etc/claude-code/managed-settings.json
  • Windows : C:\ProgramData\ClaudeCode\managed-settings.json
Exemple de configuration des paramètres gérés :
{
  "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"
  }
}
Les paramètres gérés peuvent être distribués via MDM (Mobile Device Management) ou d’autres solutions de gestion d’appareils. Les variables d’environnement définies dans le fichier de paramètres gérés ont une haute priorité et ne peuvent pas être remplacées par les utilisateurs.

Détails de la configuration

Variables de configuration courantes

Variable d’environnementDescriptionExemples de valeurs
CLAUDE_CODE_ENABLE_TELEMETRYActive la collecte de télémétrie (obligatoire)1
OTEL_METRICS_EXPORTERType(s) d’exportateur de métriques (séparés par des virgules)console, otlp, prometheus
OTEL_LOGS_EXPORTERType(s) d’exportateur de journaux/événements (séparés par des virgules)console, otlp
OTEL_EXPORTER_OTLP_PROTOCOLProtocole pour l’exportateur OTLP (tous les signaux)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINTPoint de terminaison du collecteur OTLP (tous les signaux)http://localhost:4317
OTEL_EXPORTER_OTLP_METRICS_PROTOCOLProtocole pour les métriques (remplace le général)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_METRICS_ENDPOINTPoint de terminaison des métriques OTLP (remplace le général)http://localhost:4318/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_PROTOCOLProtocole pour les journaux (remplace le général)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTPoint de terminaison des journaux OTLP (remplace le général)http://localhost:4318/v1/logs
OTEL_EXPORTER_OTLP_HEADERSEn-têtes d’authentification pour OTLPAuthorization=Bearer token
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEYClé client pour l’authentification mTLSChemin d’accès au fichier de clé client
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATECertificat client pour l’authentification mTLSChemin d’accès au fichier de certificat client
OTEL_METRIC_EXPORT_INTERVALIntervalle d’export en millisecondes (par défaut : 60000)5000, 60000
OTEL_LOGS_EXPORT_INTERVALIntervalle d’export des journaux en millisecondes (par défaut : 5000)1000, 10000
OTEL_LOG_USER_PROMPTSActiver la journalisation du contenu des invites utilisateur (par défaut : désactivé)1 pour activer

Contrôle de la cardinalité des métriques

Les variables d’environnement suivantes contrôlent les attributs inclus dans les métriques pour gérer la cardinalité :
Variable d’environnementDescriptionValeur par défautExemple pour désactiver
OTEL_METRICS_INCLUDE_SESSION_IDInclure l’attribut session.id dans les métriquestruefalse
OTEL_METRICS_INCLUDE_VERSIONInclure l’attribut app.version dans les métriquesfalsetrue
OTEL_METRICS_INCLUDE_ACCOUNT_UUIDInclure l’attribut user.account_uuid dans les métriquestruefalse
Ces variables aident à contrôler la cardinalité des métriques, ce qui affecte les exigences de 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 plus faibles, mais des données moins granulaires pour l’analyse.

En-têtes dynamiques

Pour les environnements d’entreprise qui nécessitent une authentification dynamique, vous pouvez configurer un script pour générer les en-têtes de manière dynamique :

Configuration des paramètres

Ajoutez à votre .claude/settings.json :
{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}

Exigences du script

Le script doit générer un JSON valide avec des paires clé-valeur de chaîne représentant les en-têtes HTTP :
#!/bin/bash
# Exemple : plusieurs en-têtes
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

Limitations importantes

Les en-têtes sont récupérés uniquement au démarrage, pas pendant l’exécution. Ceci est dû aux limitations de l’architecture de l’exportateur OpenTelemetry. Pour les scénarios nécessitant un renouvellement fréquent des jetons, utilisez un collecteur OpenTelemetry comme proxy qui peut renouveler ses propres en-têtes.

Support des organisations multi-équipes

Les organisations avec plusieurs équipes ou départements peuvent ajouter des attributs personnalisés pour distinguer les différents groupes à l’aide de la variable d’environnement OTEL_RESOURCE_ATTRIBUTES :
# Ajouter des attributs personnalisés pour l'identification de l'équipe
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"
Ces attributs personnalisés seront inclus dans toutes les métriques et tous les événements, ce qui vous permet de :
  • Filtrer les métriques par équipe ou département
  • Suivre les coûts par centre de coûts
  • Créer des tableaux de bord spécifiques à l’équipe
  • Configurer des alertes pour des équipes spécifiques
Exigences importantes de formatage pour OTEL_RESOURCE_ATTRIBUTES :La variable d’environnement OTEL_RESOURCE_ATTRIBUTES suit la spécification W3C Baggage, qui a des exigences de formatage strictes :
  • Aucun espace autorisé : Les valeurs ne peuvent pas contenir d’espaces. Par exemple, user.organizationName=My Company est invalide
  • Format : Doit être des paires clé=valeur séparées par des virgules : key1=value1,key2=value2
  • Caractères autorisés : Uniquement les caractères US-ASCII excluant les caractères de contrôle, les espaces, les guillemets doubles, les virgules, les points-virgules et les barres obliques inverses
  • Caractères spéciaux : Les caractères en dehors de la plage autorisée doivent être codés en pourcentage
Exemples :
# ❌ Invalide - contient des espaces
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

# ✅ Valide - utilisez des traits de soulignement ou camelCase à la place
export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

# ✅ Valide - codez en pourcentage les caractères spéciaux si nécessaire
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"
Remarque : Mettre entre guillemets la paire clé=valeur entière (par exemple, "key=value with spaces") n’est pas pris en charge par la spécification OpenTelemetry et entraînera le préfixage des attributs avec des guillemets.

Exemples de configurations

# Débogage de console (intervalles de 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

# Plusieurs exportateurs
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

# Points de terminaison/backends différents pour les métriques et les journaux
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

# Métriques uniquement (pas d'événements/journaux)
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

# Événements/journaux uniquement (pas de métriques)
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étriques et événements disponibles

Attributs standard

Toutes les métriques et tous les événements partagent ces attributs standard :
AttributDescriptionContrôlé par
session.idIdentifiant de session uniqueOTEL_METRICS_INCLUDE_SESSION_ID (par défaut : true)
app.versionVersion actuelle de Claude CodeOTEL_METRICS_INCLUDE_VERSION (par défaut : false)
organization.idUUID de l’organisation (si authentifié)Toujours inclus si disponible
user.account_uuidUUID du compte (si authentifié)OTEL_METRICS_INCLUDE_ACCOUNT_UUID (par défaut : true)
terminal.typeType de terminal (par exemple, iTerm.app, vscode, cursor, tmux)Toujours inclus si détecté

Métriques

Claude Code exporte les métriques suivantes :
Nom de la métriqueDescriptionUnité
claude_code.session.countNombre de sessions CLI démarréescount
claude_code.lines_of_code.countNombre de lignes de code modifiéescount
claude_code.pull_request.countNombre de demandes de tirage crééescount
claude_code.commit.countNombre de commits git crééscount
claude_code.cost.usageCoût de la session Claude CodeUSD
claude_code.token.usageNombre de jetons utiliséstokens
claude_code.code_edit_tool.decisionNombre de décisions de permission de l’outil d’édition de codecount
claude_code.active_time.totalTemps actif total en secondess

Détails des métriques

Compteur de sessions

Incrémenté au début de chaque session. Attributs :

Compteur de lignes de code

Incrémenté lorsque du code est ajouté ou supprimé. Attributs :

Compteur de demandes de tirage

Incrémenté lors de la création de demandes de tirage via Claude Code. Attributs :

Compteur de commits

Incrémenté lors de la création de commits git via Claude Code. Attributs :

Compteur de coûts

Incrémenté après chaque demande d’API. Attributs :
  • Tous les attributs standard
  • model : Identifiant du modèle (par exemple, “claude-sonnet-4-5-20250929”)

Compteur de jetons

Incrémenté après chaque demande d’API. Attributs :
  • Tous les attributs standard
  • type : ("input", "output", "cacheRead", "cacheCreation")
  • model : Identifiant du modèle (par exemple, “claude-sonnet-4-5-20250929”)

Compteur de décisions de l’outil d’édition de code

Incrémenté lorsque l’utilisateur accepte ou rejette l’utilisation de l’outil Edit, Write ou NotebookEdit. Attributs :
  • Tous les attributs standard
  • tool : Nom de l’outil ("Edit", "Write", "NotebookEdit")
  • decision : Décision de l’utilisateur ("accept", "reject")
  • language : Langage de programmation du fichier édité (par exemple, "TypeScript", "Python", "JavaScript", "Markdown"). Retourne "unknown" pour les extensions de fichier non reconnues.

Compteur de temps actif

Suit le temps réel passé à utiliser activement Claude Code (pas le temps d’inactivité). Cette métrique est incrémentée lors des interactions utilisateur telles que la saisie d’invites ou la réception de réponses. Attributs :

Événements

Claude Code exporte les événements suivants via les journaux/événements OpenTelemetry (lorsque OTEL_LOGS_EXPORTER est configuré) :

Événement d’invite utilisateur

Enregistré lorsqu’un utilisateur soumet une invite. Nom de l’événement : claude_code.user_prompt Attributs :
  • Tous les attributs standard
  • event.name : "user_prompt"
  • event.timestamp : Horodatage ISO 8601
  • prompt_length : Longueur de l’invite
  • prompt : Contenu de l’invite (masqué par défaut, activez avec OTEL_LOG_USER_PROMPTS=1)

Événement de résultat d’outil

Enregistré lorsqu’un outil termine son exécution. Nom de l’événement : claude_code.tool_result Attributs :
  • Tous les attributs standard
  • event.name : "tool_result"
  • event.timestamp : Horodatage ISO 8601
  • tool_name : Nom de l’outil
  • success : "true" ou "false"
  • duration_ms : Temps d’exécution en millisecondes
  • error : Message d’erreur (en cas d’échec)
  • decision : Soit "accept" soit "reject"
  • source : Source de la décision - "config", "user_permanent", "user_temporary", "user_abort", ou "user_reject"
  • tool_parameters : Chaîne JSON contenant les paramètres spécifiques à l’outil (si disponible)
    • Pour l’outil Bash : inclut bash_command, full_command, timeout, description, sandbox

Événement de demande d’API

Enregistré pour chaque demande d’API à Claude. Nom de l’événement : claude_code.api_request Attributs :
  • Tous les attributs standard
  • event.name : "api_request"
  • event.timestamp : Horodatage ISO 8601
  • model : Modèle utilisé (par exemple, “claude-sonnet-4-5-20250929”)
  • cost_usd : Coût estimé en USD
  • duration_ms : Durée de la demande en millisecondes
  • input_tokens : Nombre de jetons d’entrée
  • output_tokens : Nombre de jetons de sortie
  • cache_read_tokens : Nombre de jetons lus à partir du cache
  • cache_creation_tokens : Nombre de jetons utilisés pour la création du cache

Événement d’erreur d’API

Enregistré lorsqu’une demande d’API à Claude échoue. Nom de l’événement : claude_code.api_error Attributs :
  • Tous les attributs standard
  • event.name : "api_error"
  • event.timestamp : Horodatage ISO 8601
  • model : Modèle utilisé (par exemple, “claude-sonnet-4-5-20250929”)
  • error : Message d’erreur
  • status_code : Code de statut HTTP (si applicable)
  • duration_ms : Durée de la demande en millisecondes
  • attempt : Numéro de tentative (pour les demandes réessayées)

Événement de décision d’outil

Enregistré lorsqu’une décision de permission d’outil est prise (accepter/rejeter). Nom de l’événement : claude_code.tool_decision Attributs :
  • Tous les attributs standard
  • event.name : "tool_decision"
  • event.timestamp : Horodatage ISO 8601
  • tool_name : Nom de l’outil (par exemple, “Read”, “Edit”, “Write”, “NotebookEdit”, etc.)
  • decision : Soit "accept" soit "reject"
  • source : Source de la décision - "config", "user_permanent", "user_temporary", "user_abort", ou "user_reject"

Interprétation des données de métriques et d’événements

Les métriques exportées par Claude Code fournissent des informations précieuses sur les modèles d’utilisation et la productivité. Voici quelques visualisations et analyses courantes que vous pouvez créer :

Surveillance de l’utilisation

MétriqueOpportunité d’analyse
claude_code.token.usageVentiler par type (entrée/sortie), utilisateur, équipe ou modèle
claude_code.session.countSuivre l’adoption et l’engagement au fil du temps
claude_code.lines_of_code.countMesurer la productivité en suivant les ajouts/suppressions de code
claude_code.commit.count & claude_code.pull_request.countComprendre l’impact sur les flux de travail de développement

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 à utilisation élevée pour optimisation
Les métriques de coûts sont des approximations. Pour les données de facturation officielles, consultez votre fournisseur d’API (Claude Console, AWS Bedrock ou Google Cloud Vertex).

Alertes et segmentation

Les alertes courantes à considérer :
  • Pics de coûts
  • Consommation de jetons inhabituelle
  • Volume de session élevé d’utilisateurs spécifiques
Toutes les métriques peuvent être segmentées par user.account_uuid, organization.id, session.id, model et app.version.

Analyse des événements

Les données d’événement fournissent des informations détaillées sur les interactions de Claude Code : Modèles d’utilisation des outils : Analysez les événements de résultat d’outil pour identifier :
  • Les outils les plus fréquemment utilisés
  • Les taux de succès des outils
  • Les temps d’exécution moyens des outils
  • Les modèles d’erreur par type d’outil
Surveillance des performances : Suivez les durées des demandes d’API et les temps d’exécution des outils pour identifier les goulots d’étranglement de performance.

Considérations relatives aux backends

Votre choix de backends de métriques et de journaux déterminera les types d’analyses que vous pouvez effectuer :

Pour les métriques :

  • Bases de données de séries chronologiques (par exemple, Prometheus) : Calculs de taux, métriques agrégées
  • Magasins en colonnes (par exemple, ClickHouse) : Requêtes complexes, analyse d’utilisateurs uniques
  • Plates-formes d’observabilité complètes (par exemple, Honeycomb, Datadog) : Requêtes avancées, visualisation, alertes

Pour les événements/journaux :

  • Systèmes d’agrégation de journaux (par exemple, Elasticsearch, Loki) : Recherche en texte intégral, analyse de journaux
  • Magasins en colonnes (par exemple, ClickHouse) : Analyse d’événements structurés
  • Plates-formes d’observabilité complètes (par exemple, Honeycomb, Datadog) : Corrélation entre métriques et événements
Pour les organisations nécessitant des métriques d’utilisateurs actifs quotidiens/hebdomadaires/mensuels (DAU/WAU/MAU), envisagez des backends qui prennent en charge les requêtes de valeurs uniques efficaces.

Informations sur le service

Toutes les métriques et tous les événements sont exportés avec les attributs de ressource suivants :
  • service.name : claude-code
  • service.version : Version actuelle de Claude Code
  • os.type : Type de système d’exploitation (par exemple, linux, darwin, windows)
  • os.version : Chaîne de version du système d’exploitation
  • host.arch : Architecture de l’hôte (par exemple, amd64, arm64)
  • wsl.version : Numéro de version WSL (présent uniquement lors de l’exécution sur Windows Subsystem for Linux)
  • Nom du compteur : com.anthropic.claude_code

Ressources de mesure du ROI

Pour un guide complet sur la mesure du retour sur investissement pour Claude Code, y compris la configuration de la télémétrie, l’analyse des coûts, les métriques de productivité et les rapports automatisés, consultez le Guide de mesure du ROI de Claude Code. Ce référentiel fournit des configurations Docker Compose prêtes à l’emploi, des configurations Prometheus et OpenTelemetry, et des modèles pour générer des rapports de productivité intégrés à des outils comme Linear.

Considérations de sécurité/confidentialité

  • La télémétrie est opt-in 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 ou les événements
  • Le contenu des invites utilisateur est masqué par défaut - seule la longueur de l’invite est enregistrée. Pour activer la journalisation des invites utilisateur, définissez OTEL_LOG_USER_PROMPTS=1

Surveillance de Claude Code sur Amazon Bedrock

Pour des conseils détaillés sur la surveillance de l’utilisation de Claude Code pour Amazon Bedrock, consultez Implémentation de la surveillance de Claude Code (Bedrock).