Observal observabilité agents de code : sessions et traces

Un développeur vous dit : « l’agent a tourné une heure, dépensé une fortune de jetons, et n’a rien livré ». Vous n’avez ni code d’erreur ni stack trace, seulement une conversation. Pour ce cas précis, Observal observabilité agents de code veut dire conserver la session elle-même : c’est le terrain d’Observal, un dépôt open source (Apache 2.0) à environ 4,3 k étoiles sur la page GitHub lue le 9 novembre 2026. Ce billet l’aborde par la décision d’exploitation qu’il impose : que garder d’une session d’agent, où, et pour qui.

Précision de méthode : span.observer n’a pas déployé Observal. Tout ce qui suit vient du README, de la documentation du dépôt et des captures qu’il publie ; ce que je n’ai pas pu lire est marqué « non vérifié ».

Observal observabilité agents de code : de quoi parle-t-on ?

Premier piège : le nom a changé. Le README se présente désormais comme « Agentic Resource Registry » et précise « Formerly Observal : même code, mêmes mainteneurs, même licence Apache 2.0 ». La commande reste observal, et les anciens liens redirigent. Le projet est donc aujourd’hui décrit comme un registre auto-hébergé de ressources pour agents de code (skills, serveurs MCP, hooks, prompts, sandboxes), avec une couche de traçage des sessions par-dessus. Si vous cherchiez une plate-forme d’évaluation de LLM façon banc d’essai, ce n’est pas ce que la documentation décrit (voir les limites plus bas).

Faits relevés sur le dépôt : licence Apache 2.0, Python côté serveur et CLI (FastAPI, Typer), React côté interface, PostgreSQL 16 pour le registre, ClickHouse pour la télémétrie, Redis pour la file. Le dernier commit de la branche principale date du 7 novembre 2026 et le pyproject.toml porte la version 1.17.0-dev.0 ; je n’ai pas pu lire de release publiée sur la page, donc je ne cite pas de numéro stable. Le compte de forks (environ 1,1 k) vient de la même page.

Ce que le projet enregistre d’une session d’agent

Le mécanisme est simple à énoncer. Un hook ou une extension du harnais (Claude Code, Codex, Cursor, Copilot, Kiro, OpenCode, Pi, Goose, Antigravity selon le README) lit la transcription de la conversation et l’envoie au serveur. Le CLI écrit d’abord dans une boîte d’envoi locale durable, puis poste vers /api/v1/ingest/session ; le serveur renvoie la dernière position acquittée, et la livraison est décrite comme « au moins une fois, avec stockage effectivement unique ». La commande observal reconcile rejoue ce qui manque depuis la source locale.

Chaque enregistrement devient un événement : prompt, réponse, appel d’outil, résultat, mise à jour de jetons, erreur, sous-agent. Des agrégats par session (jetons, modèles, outils, durée) alimentent les tableaux de bord. La documentation est franche sur une limite utile : le détail dépend de ce que le harnais écrit, et Observal « n’intercepte pas le trafic MCP » ni n’invente de champs.

Visite de l’interface : sessions, tours, appels

La capture suivante vient du dépôt (docs/img, couverte par la licence Apache 2.0 du projet). Elle montre une session Pi : durée, 17 tours, jetons en entrée et en sortie, lectures de cache, nombre d’appels d’outils, modèles utilisés, puis la liste des tours dépliables avec leur durée.

La liste des sessions donne la vue d’ensemble : plateforme, jetons entrée et sortie, outils appelés, durée, et une colonne « Score » qui, dans cette capture de démonstration, reste vide. C’est le seul indice d’évaluation que j’y ai lu ; je ne sais pas quand ni comment cette note est alimentée.

Du ticket au diagnostic : la méthode de la documentation

Le guide « Debug agent failures » propose une marche en quatre gestes que je reformule : retrouver la session (filtres par harnais, agent, modèle, période), lire la séquence d’événements dans l’ordre, regarder le détail des appels d’outils, puis rattraper les trous de livraison avec observal reconcile. Son tableau de motifs est le plus parlant : un même outil rappelé avec les mêmes arguments signale une boucle ; un appel sans résultat suggère un arrêt brutal ou une transcription incomplète ; un appel MCP attendu mais absent veut dire que le modèle ne l’a pas choisi, ou que le harnais ne l’a pas noté.

Les commandes de la capture ci-dessous sont celles du README et de ce guide.

Installer Observal : serveur d’abord, CLI ensuite

Selon le README, il y a deux parties : un serveur à héberger (API, interface web, bases) et un CLI sur chaque poste. Le serveur exige Docker Engine 24 ou plus avec Compose v2 ; le script install-server.sh télécharge un paquet Compose, génère des fichiers de secrets, lie les ports à la boucle locale par défaut et démarre dix services. Pour le CLI : un script install.sh (macOS, Linux), install.ps1 (Windows) ou uv tool install observal-cli pour Python 3.11 ou plus. Ensuite :

observal auth login
observal doctor --patch

La seconde commande détecte le harnais et pose les hooks de télémétrie. Un conseil d’exploitant : ces installations passent par curl | bash. Téléchargez le script, lisez-le, et testez sur une machine jetable avant d’y mettre des sessions réelles. Je n’ai pas exécuté ces commandes.

Observer Observal lui-même

Le projet applique l’observabilité à sa propre pile, sans OpenTelemetry. Selon la page d’auto-observabilité : sondes /livez et /readyz (cette dernière contrôle PostgreSQL, ClickHouse et Redis), journaux JSON avec identifiant de requête propagé par l’en-tête X-Request-ID, et métriques Prometheus sur /metrics (compteur de requêtes, histogramme de latence, mémoire, CPU). Un Prometheus et un Grafana sont fournis dans le Compose.

Côté agents, la documentation de l’intégration Claude Code demande au contraire de ne pas configurer les variables OTEL_* ni CLAUDE_CODE_ENABLE_TELEMETRY : Observal ne consomme pas la télémétrie OTLP et passe uniquement par ses hooks et la réconciliation. Si vous voulez des métriques OpenTelemetry sur vos agents, c’est une autre chaîne ; voyez superviser un agent de code en entreprise. Aucune intégration Dynatrace n’est documentée par le projet, et nous n’en supposons pas.

Limites et points ouverts

• Évaluation : je n’ai trouvé ni banc d’essai ni jeu de tests de qualité. Il y a des rapports « Insights » générés par un LLM (via LiteLLM, avec le fournisseur de votre choix) qui résument ce qui aide ou gêne, ce qui est de l’analyse d’usage, pas une mesure de justesse.
• Confidentialité : une session contient vos prompts, vos sorties de commande et parfois des chemins ou des secrets. Décidez de la rétention (la page sur les bases parle de politiques de conservation) et de qui peut lire quoi avant le déploiement.
• Maturité : version en développement, changelog avec une section « Unreleased » chargée, le classement (Leaderboard) y est annoncé comme désactivé par défaut. Attendez-vous à du mouvement.
• Couverture : le niveau de détail varie selon le harnais ; une transcription pauvre donne une trace pauvre.
• Lourdeur : dix services pour surveiller des agents, c’est un vrai projet d’infrastructure.

Bonnes pratiques

• Commencez par un seul harnais et une équipe pilote, sur un serveur isolé.
• Gardez les ports en boucle locale ou derrière un proxy authentifié, comme le fait le défaut.
• Surveillez la pile avec /readyz et Prometheus ; apprenez à la réparer avec observal reconcile.
• Couplez les traces de sessions à un suivi du coût : voir le coût d’un agent IA par jetons OpenTelemetry.
• Posez des garde-fous en amont, comme dans les garde-fous d’agents IA en production. Pour un autre dépôt du même genre, lisez kagent, les agents IA sur Kubernetes.

Questions fréquentes

Observal est-il toujours le nom du projet ?

Le README se présente sous le nom Agentic Resource Registry, « anciennement Observal », avec la même base de code et la même licence ; le CLI s’appelle toujours observal.

Observal évalue-t-il la qualité des réponses d’un agent ?

Je n’ai pas lu de fonction d’évaluation automatique : le projet enregistre des sessions et produit des rapports d’usage. Une colonne de score existe dans l’interface, sans explication que j’aie pu vérifier.

Faut-il OpenTelemetry pour l’utiliser ?

Non : l’ingestion passe par des hooks et une réconciliation, et la documentation déconseille d’activer la télémétrie OTLP de Claude Code pour cette intégration.

Conclusion

Observal répond à une question concrète : que s’est-il passé dans cette session d’agent ? Sa force est la trace conservée et rejouable ; ses limites sont une pile lourde, une évaluation peu visible et un projet encore en mouvement. Pour une équipe qui laisse des agents travailler sur son code, il mérite un essai isolé, avec une décision claire sur les données conservées.

span.observer est un blog indépendant de la communauté, non affilié au projet Observal, à ses mainteneurs ni à Dynatrace LLC. Les marques citées appartiennent à leurs propriétaires. Les outils évoluent vite : vérifiez les commandes et options dans leur documentation officielle.