Surveillance
Apprenez comment activer et configurer OpenTelemetry pour Claude Code.
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 :
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 :
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’Environnement | Description | Valeurs d’Exemple |
---|---|---|
CLAUDE_CODE_ENABLE_TELEMETRY | Active la collecte de télémétrie (requis) | 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 vers le fichier de clé client |
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE | Certificat client pour l’authentification mTLS | Chemin vers le fichier de certificat client |
OTEL_METRIC_EXPORT_INTERVAL | Intervalle d’exportation en millisecondes (par défaut : 60000) | 5000 , 60000 |
OTEL_LOGS_EXPORT_INTERVAL | Intervalle d’exportation 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 quels attributs sont 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 |
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
:
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
Métriques et Événements Disponibles
Attributs Standard
Toutes les métriques et é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 (quand authentifié) | Toujours inclus quand disponible |
user.account_uuid | UUID du compte (quand authentifié) | OTEL_METRICS_INCLUDE_ACCOUNT_UUID (par défaut : true) |
terminal.type | Type 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é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 pull requests 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 tokens utilisés | tokens |
claude_code.code_edit_tool.decision | Nombre de décisions de permission d’outil d’édition de code | count |
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 (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 8601prompt_length
: Longueur de l’inviteprompt
: Contenu de l’invite (censuré par défaut, activer avecOTEL_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 8601name
: Nom de l’outilsuccess
:"true"
ou"false"
duration_ms
: Temps d’exécution en millisecondeserror
: 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 8601model
: Modèle utilisé (ex. “claude-3-5-sonnet-20241022”)cost_usd
: Coût estimé en USDduration_ms
: Durée de la requête en millisecondesinput_tokens
: Nombre de tokens d’entréeoutput_tokens
: Nombre de tokens de sortiecache_read_tokens
: Nombre de tokens lus depuis le cachecache_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 8601model
: Modèle utilisé (ex. “claude-3-5-sonnet-20241022”)error
: Message d’erreurstatus_code
: Code de statut HTTP (si applicable)duration_ms
: Durée de la requête en millisecondesattempt
: 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 8601tool_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étrique | Opportunité d’Analyse |
---|---|
claude_code.token.usage | Décomposer 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é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