Surveillance

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 est de la responsabilité de l’utilisateur de s’assurer que leurs backends de métriques et de journaux sont correctement configurés et que la granularité d’agrégation répond à leurs exigences de surveillance.

​

Démarrage Rapide

Configurez OpenTelemetry en utilisant les 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 requis)
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

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 et WSL : /etc/claude-code/managed-settings.json
• Windows : C:\ProgramData\ClaudeCode\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"
  }
}

​

Détails de Configuration

​

Variables de Configuration Communes

​

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é :

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.

​

En-têtes Dynamiques

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

​

Configuration des Paramètres

Ajoutez à votre .claude/settings.json :

{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}

​

Exigences du Script

Le script doit produire un JSON valide avec des paires clé-valeur de chaînes 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 seulement 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 rafraîchissement fréquent des jetons, utilisez un Collecteur OpenTelemetry comme proxy qui peut rafraîchir ses propres en-têtes.

​

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

# ❌ Invalide - contient des espaces
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

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

# ✅ Valide - encodez en pourcentage les caractères spéciaux si nécessaire
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

​

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 :

​

Métriques

Claude Code exporte les métriques suivantes :

​

Détails des Métriques

​

Compteur de Session

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

Attributs :

• Tous les attributs standard

​

Compteur de Lignes de Code

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

Attributs :

• Tous les attributs standard
• type : ("added", "removed")

​

Compteur de Pull Request

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

Attributs :

• Tous les attributs standard

​

Compteur de Commit

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

Attributs :

• Tous les attributs standard

​

Compteur de Coût

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

Attributs :

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

​

Compteur de Jetons

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

Attributs :

• Tous les attributs standard
• type : ("input", "output", "cacheRead", "cacheCreation")
• model : Identifiant du modèle (par exemple, “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é (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 pendant les 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 (quand OTEL_LOGS_EXPORTER est configuré) :

​

Événement d’Invite Utilisateur

Enregistré quand 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 (censuré par défaut, activez avec OTEL_LOG_USER_PROMPTS=1)

​

Événement de Résultat d’Outil

Enregistré quand 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 (si échec)
• decision : Soit "accept" soit "reject"
• source : Source de 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 (quand disponible)
  • Pour l’outil Bash : inclut bash_command, full_command, timeout, description, sandbox

​

Événement de Requête API

Enregistré pour chaque requête API vers 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-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 jetons d’entrée
• output_tokens : Nombre de jetons de sortie
• cache_read_tokens : Nombre de jetons lus depuis le cache
• cache_creation_tokens : Nombre de jetons utilisés pour la création de cache

​

Événement d’Erreur API

Enregistré quand une requête API vers 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-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 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”, “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 de l’Utilisation

​

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

​

Alertes et Segmentation

Alertes communes à considérer :

• Pics de coût
• Consommation inhabituelle de jetons
• 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 : 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 de requête API et les temps d’exécution des 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 (par exemple, Prometheus) : Calculs de taux, métriques agrégées
• Magasins colonnaires (par exemple, ClickHouse) : Requêtes complexes, analyse d’utilisateurs uniques
• Plateformes 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 colonnaires (par exemple, ClickHouse) : Analyse d’événements structurés
• Plateformes 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), considérez les backends qui supportent des requêtes de valeurs uniques efficaces.

​

Informations de Service

Toutes les métriques et é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 seulement 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, incluant la configuration de 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 Claude Code. Ce dépôt 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 avec 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 événements
• Le contenu des invites utilisateur est censuré par défaut - seule la longueur de l’invite est enregistrée. Pour activer l’enregistrement des invites utilisateur, définissez OTEL_LOG_USER_PROMPTS=1