Surveillance

​

Démarrage rapide

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

# 2. Choisir les exportateurs (les deux sont facultatifs - 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

​

Configuration de l’administrateur

{
  "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.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}

​

Détails de la configuration

​

Variables de configuration courantes

​

Contrôle de la cardinalité des métriques

​

En-têtes dynamiques

​

Configuration des paramètres

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

​

Exigences du script

#!/bin/bash
# Exemple : plusieurs en-têtes
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

​

Comportement d’actualisation

​

Support des organisations multi-équipes

# Ajouter des attributs personnalisés pour l'identification de l'équipe
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

• 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

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

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

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

​

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.example.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.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

• prompt.id : UUID corrélant une invite utilisateur avec tous les événements suivants jusqu’à l’invite suivante. Voir Attributs de corrélation d’événements.
• workspace.host_paths : répertoires d’espace de travail hôte sélectionnés dans l’application de bureau, sous forme de tableau de chaînes

​

Métriques

​

Détails des métriques

​

Compteur de sessions

• Tous les attributs standard

​

Compteur de lignes de code

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

​

Compteur de demandes de tirage

• Tous les attributs standard

​

Compteur de commits

• Tous les attributs standard

​

Compteur de coûts

• Tous les attributs standard
• model : Identifiant du modèle (par exemple, « claude-sonnet-4-6 »)

​

Compteur de jetons

• Tous les attributs standard
• type : ("input", "output", "cacheRead", "cacheCreation")
• model : Identifiant du modèle (par exemple, « claude-sonnet-4-6 »)

​

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

• Tous les attributs standard
• tool_name : Nom de l’outil ("Edit", "Write", "NotebookEdit")
• decision : Décision de l’utilisateur ("accept", "reject")
• source : Source de la décision - "config", "hook", "user_permanent", "user_temporary", "user_abort", ou "user_reject"
• language : Langage de programmation du fichier édité, tel que "TypeScript", "Python", "JavaScript", ou "Markdown". Retourne "unknown" pour les extensions de fichier non reconnues.

​

Compteur de temps actif

• Tous les attributs standard
• type : "user" pour les interactions au clavier, "cli" pour l’exécution d’outils et les réponses IA

​

Événements

​

Attributs de corrélation d’événements

​

Événement d’invite utilisateur

• Tous les attributs standard
• event.name : "user_prompt"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• 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

• Tous les attributs standard
• event.name : "tool_result"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• 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_type : Soit "accept" soit "reject"
• decision_source : Source de la décision - "config", "hook", "user_permanent", "user_temporary", "user_abort", ou "user_reject"
• tool_result_size_bytes : Taille du résultat de l’outil en octets
• mcp_server_scope : Identifiant de portée du serveur MCP (pour les outils MCP)
• 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, dangerouslyDisableSandbox, et git_commit_id (le SHA du commit, lorsqu’une commande git commit réussit)
  • Pour les outils MCP (lorsque OTEL_LOG_TOOL_DETAILS=1) : inclut mcp_server_name, mcp_tool_name
  • Pour l’outil Skill (lorsque OTEL_LOG_TOOL_DETAILS=1) : inclut skill_name
• tool_input (lorsque OTEL_LOG_TOOL_DETAILS=1) : Arguments d’outil sérialisés en JSON. Les valeurs individuelles dépassant 512 caractères sont tronquées, et la charge utile complète est limitée à environ 4 K caractères. S’applique à tous les outils, y compris les outils MCP.

​

Événement de demande d’API

• Tous les attributs standard
• event.name : "api_request"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• model : Modèle utilisé (par exemple, « claude-sonnet-4-6 »)
• 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
• speed : "fast" ou "normal", indiquant si le mode rapide était actif

​

Événement d’erreur d’API

• Tous les attributs standard
• event.name : "api_error"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• model : Modèle utilisé (par exemple, « claude-sonnet-4-6 »)
• error : Message d’erreur
• status_code : Code de statut HTTP sous forme de chaîne, ou "undefined" pour les erreurs non-HTTP
• duration_ms : Durée de la demande en millisecondes
• attempt : Numéro de tentative (pour les demandes réessayées)
• speed : "fast" ou "normal", indiquant si le mode rapide était actif

​

Événement de décision d’outil

• Tous les attributs standard
• event.name : "tool_decision"
• event.timestamp : Horodatage ISO 8601
• event.sequence : Compteur monotone croissant pour ordonner les événements au sein d’une session
• tool_name : Nom de l’outil (par exemple, « Read », « Edit », « Write », « NotebookEdit »)
• decision : Soit "accept" soit "reject"
• source : Source de la décision - "config", "hook", "user_permanent", "user_temporary", "user_abort", ou "user_reject"

​

Interpréter les données de métriques et d’événements

​

Surveillance de l’utilisation

​

Surveillance des coûts

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

​

Alertes et segmentation

• Pics de coûts
• Consommation de jetons inhabituelle
• Volume de session élevé d’utilisateurs spécifiques

​

Analyse des événements

• Les outils les plus fréquemment utilisés
• Les taux de réussite des outils
• Les temps d’exécution moyens des outils
• Les modèles d’erreur par type d’outil

​

Considérations relatives aux backends

​

Pour les métriques

• Bases de données de séries chronologiques (par exemple, Prometheus) : Calculs de taux, métriques agrégées
• Magasins colonnaires (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 colonnaires (par exemple, ClickHouse) : Analyse d’événements structurés
• Plates-formes d’observabilité complètes (par exemple, Honeycomb, Datadog) : Corrélation entre les métriques et les événements

​

Informations sur le service

• 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

​

Sécurité et confidentialité

• La télémétrie est opt-in et nécessite une configuration explicite
• Les contenus de fichiers bruts et les extraits de code ne sont pas inclus dans les métriques ou les événements. Les événements d’exécution d’outils incluent les commandes bash et les chemins de fichiers dans le champ tool_parameters, qui peuvent contenir des valeurs sensibles. Si vos commandes peuvent inclure des secrets, configurez votre backend de télémétrie pour filtrer ou masquer tool_parameters
• Lorsqu’authentifié via OAuth, user.email est inclus dans les attributs de télémétrie. Si cela pose un problème pour votre organisation, travaillez avec votre backend de télémétrie pour filtrer ou masquer ce champ
• Le contenu des invites utilisateur n’est pas collecté par défaut. Seule la longueur de l’invite est enregistrée. Pour inclure le contenu de l’invite, définissez OTEL_LOG_USER_PROMPTS=1
• Les arguments d’entrée d’outil ne sont pas enregistrés par défaut. Pour les inclure, définissez OTEL_LOG_TOOL_DETAILS=1. Lorsqu’activé, les événements tool_result incluent les noms de serveur MCP/outil et les noms de compétences plus un attribut tool_input avec les chemins de fichiers, les URL, les modèles de recherche et d’autres arguments. Les valeurs individuelles dépassant 512 caractères sont tronquées et le total est limité à environ 4 K caractères, mais les arguments peuvent toujours contenir des valeurs sensibles. Configurez votre backend de télémétrie pour filtrer ou masquer tool_input selon les besoins

​

Surveiller Claude Code sur Amazon Bedrock