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 :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.
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
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’environnement | Description | Exemples de valeurs |
|---|---|---|
CLAUDE_CODE_ENABLE_TELEMETRY | Active la collecte de télémétrie (obligatoire) | 1 |
OTEL_METRICS_EXPORTER | Type(s) d’exportateur de métriques (séparés par des virgules) | console, otlp, prometheus |
OTEL_LOGS_EXPORTER | Type(s) d’exportateur de journaux/événements (séparés par des virgules) | console, otlp |
OTEL_EXPORTER_OTLP_PROTOCOL | Protocole pour l’exportateur OTLP (tous les signaux) | grpc, http/json, http/protobuf |
OTEL_EXPORTER_OTLP_ENDPOINT | Point de terminaison du collecteur OTLP (tous les signaux) | http://localhost:4317 |
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL | Protocole pour les métriques (remplace le général) | grpc, http/json, http/protobuf |
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | Point de terminaison des métriques OTLP (remplace le général) | http://localhost:4318/v1/metrics |
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL | Protocole pour les journaux (remplace le général) | grpc, http/json, http/protobuf |
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT | Point de terminaison des journaux OTLP (remplace le général) | http://localhost:4318/v1/logs |
OTEL_EXPORTER_OTLP_HEADERS | En-têtes d’authentification pour OTLP | Authorization=Bearer token |
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY | Clé client pour l’authentification mTLS | Chemin d’accès au fichier de clé client |
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE | Certificat client pour l’authentification mTLS | Chemin d’accès au fichier de certificat client |
OTEL_METRIC_EXPORT_INTERVAL | Intervalle d’export en millisecondes (par défaut : 60000) | 5000, 60000 |
OTEL_LOGS_EXPORT_INTERVAL | Intervalle d’export des journaux en millisecondes (par défaut : 5000) | 1000, 10000 |
OTEL_LOG_USER_PROMPTS | Activer 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’environnement | Description | Valeur par défaut | Exemple pour désactiver |
|---|---|---|---|
OTEL_METRICS_INCLUDE_SESSION_ID | Inclure l’attribut session.id dans les métriques | true | false |
OTEL_METRICS_INCLUDE_VERSION | Inclure l’attribut app.version dans les métriques | false | true |
OTEL_METRICS_INCLUDE_ACCOUNT_UUID | Inclure l’attribut user.account_uuid dans les métriques | true | false |
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 :
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 :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’environnementOTEL_RESOURCE_ATTRIBUTES :
- 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 Remarque : Mettre entre guillemets la paire clé=valeur entière (par exemple,
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 Companyest 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
"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
Métriques et événements disponibles
Attributs standard
Toutes les métriques et tous les événements partagent ces attributs standard :| Attribut | Description | Contrôlé par |
|---|---|---|
session.id | Identifiant de session unique | OTEL_METRICS_INCLUDE_SESSION_ID (par défaut : true) |
app.version | Version actuelle de Claude Code | OTEL_METRICS_INCLUDE_VERSION (par défaut : false) |
organization.id | UUID de l’organisation (si authentifié) | Toujours inclus si disponible |
user.account_uuid | UUID du compte (si authentifié) | OTEL_METRICS_INCLUDE_ACCOUNT_UUID (par défaut : true) |
terminal.type | Type 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étrique | Description | Unité |
|---|---|---|
claude_code.session.count | Nombre de sessions CLI démarrées | count |
claude_code.lines_of_code.count | Nombre de lignes de code modifiées | count |
claude_code.pull_request.count | Nombre de demandes de tirage créées | count |
claude_code.commit.count | Nombre de commits git créés | count |
claude_code.cost.usage | Coût de la session Claude Code | USD |
claude_code.token.usage | Nombre de jetons utilisés | tokens |
claude_code.code_edit_tool.decision | Nombre de décisions de permission de l’outil d’édition de code | count |
claude_code.active_time.total | Temps actif total en secondes | s |
Détails des métriques
Compteur de sessions
Incrémenté au début de chaque session. Attributs :- Tous les attributs standard
Compteur de lignes de code
Incrémenté lorsque du code est ajouté ou supprimé. Attributs :- Tous les attributs standard
type: ("added","removed")
Compteur de demandes de tirage
Incrémenté lors de la création de demandes de tirage via Claude Code. Attributs :- Tous les attributs standard
Compteur de commits
Incrémenté lors de la création de commits git via Claude Code. Attributs :- Tous les attributs standard
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 :- Tous les attributs standard
Événements
Claude Code exporte les événements suivants via les journaux/événements OpenTelemetry (lorsqueOTEL_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 8601prompt_length: Longueur de l’inviteprompt: Contenu de l’invite (masqué par défaut, activez avecOTEL_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 8601tool_name: Nom de l’outilsuccess:"true"ou"false"duration_ms: Temps d’exécution en millisecondeserror: 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
- Pour l’outil Bash : inclut
É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 8601model: Modèle utilisé (par exemple, “claude-sonnet-4-5-20250929”)cost_usd: Coût estimé en USDduration_ms: Durée de la demande en millisecondesinput_tokens: Nombre de jetons d’entréeoutput_tokens: Nombre de jetons de sortiecache_read_tokens: Nombre de jetons lus à partir du cachecache_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 8601model: Modèle utilisé (par exemple, “claude-sonnet-4-5-20250929”)error: Message d’erreurstatus_code: Code de statut HTTP (si applicable)duration_ms: Durée de la demande en millisecondesattempt: 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 8601tool_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étrique | Opportunité d’analyse |
|---|---|
claude_code.token.usage | Ventiler par type (entrée/sortie), utilisateur, équipe ou modèle |
claude_code.session.count | Suivre l’adoption et l’engagement au fil du temps |
claude_code.lines_of_code.count | Mesurer la productivité en suivant les ajouts/suppressions de code |
claude_code.commit.count & claude_code.pull_request.count | Comprendre l’impact sur les flux de travail de développement |
Surveillance des coûts
La métriqueclaude_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
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
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
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-codeservice.version: Version actuelle de Claude Codeos.type: Type de système d’exploitation (par exemple,linux,darwin,windows)os.version: Chaîne de version du système d’exploitationhost.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