Observabilité des agents : voir ce que ton agent fait vraiment

Les logs, le suivi des coûts et le support OpenTelemetry transforment une session boîte noire en données traçables – essentiel dès que les agents tournent de façon automatisée ou en équipe.

Pourquoi observer devient important

Tant que tu travailles seul·e et de façon interactive avec un agent, tu vois directement ce qui se passe. Dès que les agents tournent de façon automatisée, en équipe ou en CI/CD, tu as besoin de vraies données : ce que l'agent a fait, ce que ça a coûté, quels outils ont été appelés.

Les logs de session comme couche de base

Claude Code écrit chaque session sous forme de fichier JSONL sur le disque (sous ~/.claude/projects/). Le format est interne et change d'une version à l'autre – ne parse pas ces fichiers directement, utilise plutôt /export ou les interfaces documentées. Même sur les plans par abonnement, /usage affiche une répartition des coûts et de l'utilisation directement dans le terminal.

Suivi des coûts dans le terminal

La commande /usage affiche le coût estimé et l'utilisation de tokens de la session en cours directement dans le terminal, ventilés par skills, subagents, plugins et serveurs MCP individuels. Ce chiffre est une estimation locale calculée à partir des comptages de tokens, pas une facture officielle.

OpenTelemetry pour la vue d'ensemble

À l'échelle d'une équipe ou d'une organisation, Claude Code propose un support natif d'OpenTelemetry : avec CLAUDE_CODE_ENABLE_TELEMETRY=1, tu exportes des métriques, des événements et, en option, des traces vers ton propre backend d'observabilité (Prometheus, Grafana, Datadog, etc.). Tu obtiens ainsi les coûts, l'utilisation des outils et les événements de sécurité de façon centralisée pour tous les utilisateurs·rices – au lieu de collecter les logs machine par machine.

EXEMPLE

`export CLAUDE_CODE_ENABLE_TELEMETRY=1`, `export OTEL_METRICS_EXPORTER=otlp` et `export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317` avant de lancer `claude` suffisent pour envoyer des métriques vers une installation locale d'OpenTelemetry Collector.

🛠️ EXERCICE — À TOI DE JOUER

Active en local la transparence des coûts et des sessions dans Claude Code, sans mettre en place de stack d'observabilité externe.

Exécute /usage dans une session Claude Code en cours et lis la répartition par skills, subagents et serveurs MCP.
Ouvre /usage et regarde la répartition des coûts et de l'utilisation.
Configure à titre de test CLAUDE_CODE_ENABLE_TELEMETRY=1 et OTEL_METRICS_EXPORTER=console, redémarre claude et observe quelles métriques apparaissent dans la console.

✅ AUTO-VÉRIFICATION

☐ As-tu pu déterminer grâce à /usage quelle partie de la session (par exemple un serveur MCP précis) a consommé le plus de contexte ?
☐ Qu'y avait-il dans la ligne JSONL – est-ce que ça t'a suffi pour retracer les coûts ?
☐ Laquelle des variables OTEL_LOG_* n'activerais-tu PAS dans une configuration d'équipe réelle, parce qu'elle exporte des données trop sensibles ?

QUIZ RAPIDE

Comment actives-tu le plus simplement l'export OpenTelemetry dans Claude Code ?