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 temporelles 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 incombe à 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 susceptibles de changer.

Démarrage Rapide

Configurez OpenTelemetry en utilisant des 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 seulement 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 requise)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. Pour le débogage : réduire les intervalles d'exportation
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’exportation par défaut sont de 60 secondes pour les métriques et de 5 secondes pour les journaux. Pendant la configuration, vous pourriez vouloir utiliser des intervalles plus courts à des fins de débogage. N’oubliez pas de les réinitialiser pour l’utilisation en production.

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 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 se trouve à :

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

Exemple de configuration de 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 précédence élevée et ne peuvent pas être remplacées par les utilisateurs.

Détails de Configuration

Variables de Configuration Communes

Variable d’EnvironnementDescriptionValeurs d’Exemple
CLAUDE_CODE_ENABLE_TELEMETRYActive la collecte de télémétrie (requis)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 vers le fichier de clé client
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATECertificat client pour l’authentification mTLSChemin vers le fichier de certificat client
OTEL_METRIC_EXPORT_INTERVALIntervalle d’exportation en millisecondes (par défaut : 60000)5000, 60000
OTEL_LOGS_EXPORT_INTERVALIntervalle d’exportation 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 quels attributs sont 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 de requête dans votre backend de métriques. Une cardinalité plus faible signifie généralement de meilleures performances et des coûts de stockage plus bas, mais des données moins granulaires pour l’analyse.

Support d’Organisation Multi-Équipes

Les organisations avec plusieurs équipes ou départements peuvent ajouter des attributs personnalisés pour distinguer entre différents groupes en utilisant la variable d’environnement OTEL_RESOURCE_ATTRIBUTES :

# Ajouter des attributs personnalisés pour l'identification d'é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 événements, vous permettant de :

  • Filtrer les métriques par équipe ou département
  • Suivre les coûts par centre de coût
  • Créer des tableaux de bord spécifiques à l’équipe
  • Configurer des alertes pour des équipes spécifiques

Exemples de Configurations

# Débogage 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

# Exportateurs multiples
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 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 seulement (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 seulement (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 é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 (quand authentifié)Toujours inclus quand disponible
user.account_uuidUUID du compte (quand authentifié)OTEL_METRICS_INCLUDE_ACCOUNT_UUID (par défaut : true)
terminal.typeType de terminal (ex. iTerm.app, vscode, cursor, tmux)Toujours inclus quand détecté

Métriques

Claude Code exporte les métriques suivantes :

Nom de 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 pull requests 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 tokens utiliséstokens
claude_code.code_edit_tool.decisionNombre de décisions de permission d’outil d’édition de codecount

Détails des Métriques

Compteur de Session

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

Attributs :

Compteur de Lignes de Code

Incrémenté quand du code est ajouté ou supprimé.

Attributs :

Compteur de Pull Request

Incrémenté lors de la création de pull requests via Claude Code.

Attributs :

Compteur de Commit

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

Attributs :

Compteur de Coût

Incrémenté après chaque requête API.

Attributs :

  • Tous les attributs standard
  • model : Identifiant du modèle (ex. “claude-3-5-sonnet-20241022”)

Compteur de Token

Incrémenté après chaque requête API.

Attributs :

  • Tous les attributs standard
  • type : ("input", "output", "cacheRead", "cacheCreation")
  • model : Identifiant du modèle (ex. “claude-3-5-sonnet-20241022”)

Compteur de Décision d’Outil d’Édition de Code

Incrémenté quand l’utilisateur accepte ou rejette l’utilisation des outils Edit, MultiEdit, Write, ou NotebookEdit.

Attributs :

  • Tous les attributs standard
  • tool : Nom de l’outil ("Edit", "MultiEdit", "Write", "NotebookEdit")
  • decision : Décision de l’utilisateur ("accept", "reject")
  • language : Langage de programmation du fichier édité (ex. "TypeScript", "Python", "JavaScript", "Markdown"). Retourne "unknown" pour les extensions de fichier non reconnues.

Événements

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

Événement d’Invite Utilisateur

Enregistré quand un utilisateur soumet une invite.

Nom d’É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 (censuré par défaut, activer avec OTEL_LOG_USER_PROMPTS=1)

Événement de Résultat d’Outil

Enregistré quand un outil termine son exécution.

Nom d’Événement : claude_code.tool_result

Attributs :

  • Tous les attributs standard
  • event.name : "tool_result"
  • event.timestamp : Horodatage ISO 8601
  • name : Nom de l’outil
  • success : "true" ou "false"
  • duration_ms : Temps d’exécution en millisecondes
  • error : Message d’erreur (si échec)

Événement de Requête API

Enregistré pour chaque requête API vers Claude.

Nom d’Événement : claude_code.api_request

Attributs :

  • Tous les attributs standard
  • event.name : "api_request"
  • event.timestamp : Horodatage ISO 8601
  • model : Modèle utilisé (ex. “claude-3-5-sonnet-20241022”)
  • cost_usd : Coût estimé en USD
  • duration_ms : Durée de la requête en millisecondes
  • input_tokens : Nombre de tokens d’entrée
  • output_tokens : Nombre de tokens de sortie
  • cache_read_tokens : Nombre de tokens lus depuis le cache
  • cache_creation_tokens : Nombre de tokens utilisés pour la création de cache

Événement d’Erreur API

Enregistré quand une requête API vers Claude échoue.

Nom d’Événement : claude_code.api_error

Attributs :

  • Tous les attributs standard
  • event.name : "api_error"
  • event.timestamp : Horodatage ISO 8601
  • model : Modèle utilisé (ex. “claude-3-5-sonnet-20241022”)
  • error : Message d’erreur
  • status_code : Code de statut HTTP (si applicable)
  • duration_ms : Durée de la requête en millisecondes
  • attempt : Numéro de tentative (pour les requêtes réessayées)

Événement de Décision d’Outil

Enregistré quand une décision de permission d’outil est prise (accepter/rejeter).

Nom d’É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 (ex. “Read”, “Edit”, “MultiEdit”, “Write”, “NotebookEdit”, etc.)
  • decision : Soit "accept" soit "reject"
  • source : Source de 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 insights précieux sur les modèles d’utilisation et la productivité. Voici quelques visualisations et analyses communes que vous pouvez créer :

Surveillance d’Utilisation

MétriqueOpportunité d’Analyse
claude_code.token.usageDécomposer 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 avec :

  • Le suivi des tendances d’utilisation entre équipes ou individus
  • L’identification des sessions à forte utilisation pour l’optimisation

Les métriques de coût sont des approximations. Pour les données de facturation officielles, référez-vous à votre fournisseur d’API (Console Anthropic, AWS Bedrock, ou Google Cloud Vertex).

Alertes et Segmentation

Alertes communes à considérer :

  • Pics de coût
  • Consommation inhabituelle de tokens
  • Volume élevé de sessions 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 d’Événements

Les données d’événements fournissent des insights détaillés sur les interactions Claude Code :

Modèles d’Utilisation d’Outils : Analyser les événements de résultats d’outils 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 de Performance : Suivre les durées de requêtes API et les temps d’exécution d’outils pour identifier les goulots d’étranglement de performance.

Considérations Backend

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 temporelles (ex. Prometheus) : Calculs de taux, métriques agrégées
  • Magasins colonnaires (ex. ClickHouse) : Requêtes complexes, analyse d’utilisateurs uniques
  • Plateformes d’observabilité complètes (ex. Honeycomb, Datadog) : Requêtes avancées, visualisation, alertes

Pour les Événements/Journaux :

  • Systèmes d’agrégation de journaux (ex. Elasticsearch, Loki) : Recherche en texte intégral, analyse de journaux
  • Magasins colonnaires (ex. ClickHouse) : Analyse d’événements structurés
  • Plateformes d’observabilité complètes (ex. 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), considérez des backends qui supportent des requêtes de valeurs uniques efficaces.

Informations de Service

Toutes les métriques sont exportées avec :

  • Nom de Service : claude-code
  • Version de Service : Version actuelle de Claude Code
  • Nom de Compteur : com.anthropic.claude_code

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 événements
  • Le contenu des invites utilisateur est censuré 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