Monitorer Claude Code comme un vrai projet : le guide complet avec Grafana

Premier article de blog — IA For Tech

Pour mon tout premier article, j’aurais pu parler de prompts magiques, de workflows Cursor qui font gagner 10x, ou d’un enieme comparatif Claude Code vs Copilot.

J’ai choisi de parler de monitoring.

Oui, le monitoring. La partie que personne ne veut faire. Celle qu’on repousse toujours a “la prochaine iteration”. Celle qui n’existe dans aucun tutoriel YouTube sur l’Agentic Dev.

Et c’est exactement pour ca que j’en parle.

Pourquoi le monitoring est le grand oublie de l’Agentic Dev

Dans le monde du dev classique, le monitoring c’est deja le parent pauvre. On ship, on croise les doigts, et on attend que Sentry nous envoie un email a 3h du matin.

Avec l’Agentic Dev, c’est pire.

Les equipes adoptent Claude Code, Cursor, Copilot — souvent de maniere informelle, sans cadre, sans mesure. Chaque dev utilise l’outil a sa sauce. Le CTO n’a aucune visibilite sur les couts, sur l’adoption reelle, sur le ROI. Et quand la facture API tombe a la fin du mois, c’est la surprise.

J’appelle ca le shadow IA : l’adoption sauvage d’outils IA dans les equipes de dev, sans gouvernance, sans metriques, sans pilotage.

Le resultat ?

Des budgets licences qui explosent sans qu’on sache pourquoi
Des devs qui utilisent Opus pour des taches ou Haiku suffirait
Aucune donnee pour justifier (ou remettre en question) l’investissement IA
Impossible de mesurer si la productivite a reellement augmente

Le monitoring de l’Agentic Dev, ce n’est pas un “nice to have”. C’est la condition pour passer du mode “on essaie l’IA” au mode “l’IA fait partie de notre chaine de build”.

L’idee de depart : builder un dashboard from scratch

Mon plan initial etait simple : monter un dashboard Grafana from scratch pour monitorer l’utilisation de Claude Code dans une equipe de dev. Je voulais tout construire moi-meme — comprendre chaque metrique, chaque requete PromQL, chaque panel.

J’ai commence par brainstormer avec Claude sur les metriques pertinentes. Quels KPIs pour un CTO ? Quels indicateurs pour les devs ? Comment structurer un dashboard qui parle a tout le monde ?

Et c’est la que Claude m’a oriente vers un repo qui fait deja 80% du travail : claude-code-otel par Cole Murray.

Un stack complet : OpenTelemetry Collector + Prometheus + Loki + Grafana, le tout en Docker Compose, avec un dashboard JSON pret a importer. En 15 minutes, t’as un monitoring fonctionnel de Claude Code.

Mon reflexe de dev, c’etait de vouloir tout refaire. Mais mon reflexe d’architecte m’a dit : “Clone, comprends, customise.” On ne reinvente pas la roue quand la roue roule deja.

L’architecture du stack

Avant de rentrer dans les metriques, un mot sur le fonctionnement. C’est assez elegant.

Claude Code ──► OpenTelemetry Collector ──► Prometheus (metriques)
                                       └──► Loki (events/logs)
                                                    │
                                                    ▼
                                              Grafana (dashboards)

Claude Code exporte nativement sa telemetry via OpenTelemetry. C’est opt-in — il faut l’activer explicitement. Aucun contenu de code ou de prompt n’est envoye par defaut, uniquement des compteurs et des events structures.

Le setup tient en 3 etapes :

1. Lancer le stack :

git clone https://github.com/ColeMurray/claude-code-otel.git
cd claude-code-otel
make up

2. Configurer Claude Code (dans ~/.claude/settings.json) :

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
    "OTEL_METRIC_EXPORT_INTERVAL": "10000",
    "OTEL_LOGS_EXPORT_INTERVAL": "5000"
  }
}

3. Ouvrir Grafana sur http://localhost:3000 (admin / admin).

A ce stade, le dashboard de base couvre deja les couts par modele, le token usage, les sessions, et les outils utilises. C’est solide. Mais je voulais aller plus loin.

Customiser le dashboard : iterer metrique par metrique

Le dashboard par defaut est oriente “vue dev”. Il manque la couche manager/CTO — celle qui repond aux questions business : est-ce que ca vaut le coup ? Est-ce que l’equipe adopte vraiment ? Est-ce qu’on utilise les bons modeles ?

J’ai itere avec Claude Code pour ajouter des panels un par un, directement dans le fichier claude-code-dashboard.json. Voici chaque metrique, pourquoi elle compte, pour qui, et le prompt exact que j’ai utilise.

Metrique 1 : Cache Efficiency Ratio

Pour qui : CTO / Tech Lead

Pourquoi cette metrique : C’est probablement la metrique la plus sous-estimee. Quand Claude Code traite une requete, une partie du contexte peut etre servie depuis le cache — et ces tokens coutent 90% moins cher que les tokens input classiques. Un cache efficiency faible signifie que l’equipe paie plein pot pour du contexte qui pourrait etre reutilise.

En clair : si ce ratio est bas, l’equipe brule de l’argent pour rien.

Comment le lire : Un ratio au-dessus de 60% c’est bien. En dessous de 30%, il y a un probleme dans la facon dont les devs structurent leur contexte ou leurs sessions.

Le prompt Claude Code :

Ouvre claude-code-dashboard.json et ajoute un panel Grafana de type "gauge"
avec les seuils suivants : rouge < 30%, orange < 60%, vert >= 60%.

PromQL :
sum(rate(claude_code_token_usage_tokens_total{type="cacheRead"}[1h]))
/ (sum(rate(claude_code_token_usage_tokens_total{type="cacheRead"}[1h]))
+ sum(rate(claude_code_token_usage_tokens_total{type="input"}[1h])))

Format: percent (0-1)
Titre: "Cache Efficiency Ratio"
Description: "Ratio de tokens servis depuis le cache vs tokens input
payes plein pot. Plus c'est haut, mieux le contexte est utilise."

Place ce panel dans une nouvelle row intitulee
"📊 Manager / CTO — ROI & Adoption" apres la row "Cost & Usage Analysis".
Utilise le meme datasource que les panels existants.
Incremente le panel ID sans conflit.

Metrique 2 : Cout par ligne de code

Pour qui : CTO / Direction

Pourquoi cette metrique : C’est le proxy de ROI le plus direct. La question que tout dirigeant se pose : “On investit X€ par mois dans l’IA, ca nous coute combien par ligne de code produite ?” Ce n’est pas une metrique parfaite — une ligne de refactoring bien placee vaut plus que 500 lignes de boilerplate — mais c’est un premier indicateur tangible.

Comment le lire : Il faut le suivre dans le temps. La valeur absolue compte moins que la tendance. Si le cout par ligne augmente semaine apres semaine, c’est un signal que l’usage n’est pas optimal.

Le prompt Claude Code :

Dans claude-code-dashboard.json, ajoute un panel de type "stat"
avec l'unite en dollars.

PromQL :
sum(increase(claude_code_cost_usage_dollars_total[1d]))
/ clamp_min(sum(increase(claude_code_lines_of_code_count_lines_total[1d])), 1)

Titre: "Cout par ligne de code"
Description: "Proxy ROI — combien coute chaque ligne modifiee via Claude Code"

Place-le dans la row "📊 Manager / CTO — ROI & Adoption",
a cote du panel Cache Efficiency.

Metrique 3 : Courbe d’adoption (sessions par jour)

Pour qui : Manager / CTO

Pourquoi cette metrique : L’adoption, ca ne se decrete pas. Un CTO peut acheter 50 licences Claude Code, si personne ne s’en sert, l’investissement est perdu. Cette courbe montre la realite de l’adoption : est-ce que l’usage monte apres une formation ? Est-ce qu’il retombe apres 2 semaines ? Y a-t-il un plateau ?

C’est aussi la metrique parfaite pour mesurer l’impact d’une formation (comme celles que je propose). Avant la formation : X sessions/jour. Apres : Y sessions/jour. Le delta, c’est la preuve que ca a marche.

Comment le lire : On cherche une courbe ascendante qui se stabilise a un palier sain. Un pic suivi d’une chute, c’est le syndrome “effet wow” — l’equipe a joue avec l’outil puis est retournee a ses habitudes.

Le prompt Claude Code :

Dans claude-code-dashboard.json, ajoute un panel de type "timeseries"
avec fill opacity a 20 et un line width de 2.

PromQL :
sum(increase(claude_code_session_count_sessions_total[1d]))

Titre: "Sessions par jour"
Description: "Courbe d'adoption — nombre de sessions quotidiennes
dans le temps. Permet de mesurer l'adoption reelle post-deploiement
ou post-formation."

Place-le dans la row "📊 Manager / CTO — ROI & Adoption".
Largeur du panel : 12 (demi-ecran).

Metrique 4 : Cout quotidien total

Pour qui : CTO / Finance

Pourquoi cette metrique : La question la plus basique, et pourtant la plus frequemment sans reponse : “On depense combien par jour en Claude Code ?” Sans cette donnee, le CTO pilote a l’aveugle. Avec, il peut poser des budgets, detecter les anomalies (un dev qui fait tourner un script en boucle un dimanche), et justifier l’investissement aupres de la direction.

Comment le lire : Definir un seuil acceptable avec le CTO. Au-dessus = alerte. C’est aussi simple que ca.

Le prompt Claude Code :

Dans claude-code-dashboard.json, ajoute un panel de type "stat"
avec l'unite en dollars.
Seuils de couleur : vert par defaut, orange si > 50, rouge si > 100.

PromQL :
sum(increase(claude_code_cost_usage_dollars_total[1d]))

Titre: "Cout quotidien total"
Description: "Depense totale sur les dernieres 24h tous devs confondus"

Place-le dans la row "📊 Manager / CTO — ROI & Adoption".

Metrique 5 : Repartition des tokens (Input vs Output vs Cache)

Pour qui : Tech Lead / Architecte

Pourquoi cette metrique : Cette vue permet de comprendre la dynamique d’une equipe avec Claude Code. Beaucoup d’input et peu d’output ? Les prompts sont probablement trop verbeux ou mal structures. Peu de cache ? Le contexte n’est pas reutilise entre les requetes. Beaucoup d’output ? Peut-etre que Claude genere trop de code sans que le dev itere dessus.

C’est une metrique de diagnostic. Elle ne dit pas “ca va bien” ou “ca va mal”, elle dit “voila comment l’equipe utilise l’outil”.

Comment le lire : Idealement, le cache read devrait representer une part significative du camembert. Un bon pattern c’est : cache dominant > input > output.

Le prompt Claude Code :

Dans claude-code-dashboard.json, ajoute un panel de type "piechart".

3 series PromQL :
1. sum(rate(claude_code_token_usage_tokens_total{type="input"}[1h]))
   legendFormat: "Input"
2. sum(rate(claude_code_token_usage_tokens_total{type="output"}[1h]))
   legendFormat: "Output"
3. sum(rate(claude_code_token_usage_tokens_total{type="cacheRead"}[1h]))
   legendFormat: "Cache Read"

Titre: "Repartition des tokens"
Description: "Repartition des tokens par type — le cache read
devrait idealement dominer"

Place-le dans la row "📊 Manager / CTO — ROI & Adoption".
Largeur : 8 (un tiers d'ecran).

Metrique 6 : Cout par modele

Pour qui : CTO / Tech Lead

Pourquoi cette metrique : Claude Code donne acces a plusieurs modeles — Opus, Sonnet, Haiku — avec des tarifs tres differents. Opus coute significativement plus cher que Sonnet, qui coute plus cher que Haiku. La question : est-ce que l’equipe utilise le bon modele pour le bon usage ?

Si 80% des couts viennent d’Opus alors que la majorite des taches sont du scaffolding ou du refactoring simple, il y a un levier d’optimisation immediat. C’est comme prendre un avion first class pour aller chercher le pain.

Comment le lire : Comparer la repartition des couts avec la nature des taches. Si Opus domine et que les taches sont simples, il faut former l’equipe a choisir le bon modele selon le contexte.

Le prompt Claude Code :

Dans claude-code-dashboard.json, ajoute un panel de type "barchart"
avec stacking en mode "normal".

PromQL :
sum by (model) (increase(claude_code_cost_usage_dollars_total[1d]))

Titre: "Cout par modele"
Description: "Repartition des couts par modele — identifier si on
utilise Opus la ou Sonnet suffirait"

Place-le dans la row "📊 Manager / CTO — ROI & Adoption".
Largeur : 12 (demi-ecran).

Metrique bonus : Taux de succes des outils

Pour qui : Dev / Tech Lead

Pourquoi cette metrique : Claude Code utilise plusieurs outils en interne — bash, file edit, web search, MCP, etc. Chaque execution peut reussir ou echouer. Un taux de succes faible sur un outil specifique, c’est un signal de friction dans le workflow. Peut-etre que l’outil est mal configure, peut-etre que les permissions bloquent, peut-etre que le prompt n’est pas adapte.

Cette metrique existe deja dans le dashboard par defaut. Je la mentionne ici parce qu’elle est souvent ignoree alors qu’elle est precieuse pour le debugging et l’amelioration continue.

Le prompt complet pour tout ajouter d’un coup

Si tu veux ajouter tous les panels custom en une seule passe, voici le prompt consolide a coller dans Claude Code :

Ouvre claude-code-dashboard.json et ajoute une nouvelle row
"📊 Manager / CTO — ROI & Adoption" apres "Cost & Usage Analysis"
avec les 6 panels suivants :

1. Cache Efficiency Ratio (gauge, seuils 30%/60%)
2. Cout par ligne de code (stat, dollars)
3. Sessions par jour (timeseries, fill 20)
4. Cout quotidien total (stat, dollars, seuils 50/100)
5. Repartition tokens input/output/cache (piechart)
6. Cout par modele (barchart, stacking normal)

[voir les PromQL detailles dans les sections precedentes]

Contraintes : meme datasource, IDs sans conflit, grille coherente
(2-3 panels par ligne), descriptions dans chaque panel.
Verifie que le JSON final est valide.

Apres modification :

docker compose restart grafana

Pourquoi les KPIs changent tout

Un outil sans KPI, c’est un outil invisible.

Quand un CTO investit dans Claude Code pour son equipe, il fait un pari. Un pari sur la productivite, sur la qualite, sur la velocite. Sans metriques, ce pari reste une intuition. Avec des metriques, il devient une decision eclairee.

Et les benefices vont au-dela du simple suivi de couts :

Pour le CTO, les KPIs permettent de justifier l’investissement aupres du COMEX. “On depense X€/mois en IA, ca nous coute Y€ par ligne de code, et l’adoption a augmente de Z% depuis la formation.” C’est du concret. C’est du pilotable.

Pour le Tech Lead, les KPIs permettent d’identifier les patterns d’usage et de former l’equipe en consequence. Cache efficiency trop bas ? On fait un atelier sur la structuration du contexte. Trop d’Opus sur des taches simples ? On definit des guidelines de selection de modele.

Pour les devs, les KPIs permettent de s’auto-evaluer. Pas dans un sens flicage — dans un sens amelioration continue. “Ma cache efficiency est a 70%, celle de l’equipe est a 45%. Peut-etre que je peux partager ma facon de structurer les prompts.”

Le monitoring de l’Agentic Dev, c’est pas de la bureaucratie. C’est le passage du mode artisanal au mode industriel. C’est ce qui transforme “on utilise l’IA” en “l’IA fait partie de notre chaine de build”.

Pour aller plus loin

Quelques pistes que j’explore pour les prochaines iterations de ce dashboard :

Alertes automatiques : notification Slack quand le budget quotidien depasse un seuil, ou quand la cache efficiency chute
Correlation avec les metriques Git : croiser le nombre de PRs mergees avec le cout IA pour un vrai calcul de ROI
Vue par developpeur : pour les equipes, pouvoir comparer les patterns d’usage (sans flicage — dans un esprit de coaching)
Export de rapports : generer un rapport hebdomadaire automatique pour le CTO

Le repo officiel d’Anthropic — claude-code-monitoring-guide — propose justement un framework complet de calcul de ROI avec des templates de rapports. C’est la suite logique de ce qu’on a mis en place ici.

Recapitulatif

Etape	Temps
Cloner le repo + lancer le stack	5 min
Configurer Claude Code pour la telemetry	2 min
Valider que les donnees arrivent	5 min
Customiser avec les panels CTO/Manager	30 min
Total : dashboard complet operationnel	~45 min

En moins d’une heure, tu passes de “on utilise Claude Code en mode YOLO” a “on pilote Claude Code avec des donnees”.

C’est ca, la vraie adoption de l’IA dans une equipe de dev. Pas juste installer l’outil. Le monitorer. Le piloter. Le mesurer.

Cet article est le premier d’une serie sur l’integration de l’IA dans la chaine de build, de la Discovery au Monitoring. Si le sujet t’interesse, on en parle — mes messages LinkedIn sont ouverts.