On ne débogue pas un agent avec une ligne de log : comment on trace Notis avec Langfuse

Une défaillance d’agent ne ressemble presque jamais à une exception. Elle ressemble à un utilisateur qui dit « ce n’est pas ce que j’ai demandé », et à un fichier de log où chaque étape renvoie un 200.

C’est le problème que Langfuse résout pour nous chez Notis. Pas la disponibilité. Pas les erreurs. L’intention, la dérive, et le chemin de trente étapes entre un vocal et un document terminé.

Pourquoi une ligne de log ne sert à rien ici

Une requête classique, c’est une seule chose qui se passe. Tu journalises l’entrée, tu journalises la sortie, c’est fini.

Une requête Notis, c’est une conversation qui déclenche du travail. Quelqu’un envoie un vocal depuis WhatsApp. Il est transcrit puis confié à un agent, qui lit la mémoire à long terme, décide qu’il lui faut trois outils, lance une recherche, lance un scrape, juge le résultat trop maigre, appelle un autre outil, rédige un document et répond. Quelque part là-dedans, il peut confier une sous-tâche à un agent de code délégué qui tourne dix minutes avant de revenir.

Si la réponse est fausse, « quelle étape s’est trompée » est toute la question. Un log à plat te donne un mur de lignes triées par horodatage, sans structure parent-enfant. Impossible de voir que le scrape a renvoyé un corps vide, que le modèle a donc halluciné un résumé, et que le document est donc sûr de lui et inutile.

Langfuse nous donne l’arbre. Des generations pour les appels de modèle, des spans pour les appels d’outils, imbriqués sous une trace qui correspond à une unité de travail visible par l’utilisateur. Quand je débogue, je ne lis pas des logs. Je lis une forme.

La seule règle qu’on impose à la frontière

Voilà le truc quand on trace un assistant : les traces contiennent la vraie vie des gens. Des notes de réunion. Des e-mails clients. Des pensées inachevées dictées en voiture.

Du coup, on n’utilise le SDK Langfuse directement nulle part dans le code. On passe par un module d’encapsulation dont le seul rôle est de rendre structurellement impossible la création d’un client non masqué. Chaque client construit reçoit une fonction de masquage dès sa création, appliquée à la frontière d’export, avant que quoi que ce soit ne quitte le processus.

C’est un choix de conception délibéré, face à l’approche plus courante du « pense à expurger à chaque appel ». Les points d’appel sont ajoutés par des gens pressés. Les constructeurs, eux, sont relus une fois.

Je veux être précis sur ce que ça apporte et ce que ça n’apporte pas. Masquer les identifiants à la frontière d’export signifie que les secrets, les clés et les tokens n’atteignent pas le backend de tracing. Ça ne signifie pas que les traces sont exemptes de contenu utilisateur : la trace d’un agent qui rédige un document contient le document. C’est pour ça que la politique de sécurité de Langfuse compte pour nous, et qu’il est cité nommément dans la présentation des fournisseurs de la plateforme de notre centre d’aide, plutôt qu’enfoui dans un PDF de sous-traitants.

Le bug qui nous a appris à mettre les clients en cache

C’est mon préféré, parce que c’est le genre de chose qu’on ne trouve qu’en production.

Chaque instance Langfuse démarre ses propres threads d’ingestion, son propre consommateur d’upload de médias et son propre pool de connexions HTTP. Seul un shutdown() explicite les arrête. Nos routeurs construisaient un client à chaque étape de requête, avec des identifiants constants pour tout le processus.

Tu vois où ça mène. On perdait environ cent threads toutes les dix minutes. La mémoire grimpait de façon linéaire. Au bout d’un moment, le processus se faisait tuer pour manque de mémoire, redémarrait et recommençait. Rien dans les logs applicatifs ne disait « le tracing est en train de dévorer ton serveur », parce que le tracing fonctionnait parfaitement.

La correction est ennuyeuse : mettre en cache un client par signature de constructeur distincte, derrière un verrou. C’est ce que prévoit le SDK. Mais on ne l’a trouvé que parce que la fuite était assez linéaire et prévisible pour qu’on fasse le lien, ce qui est en soi un argument pour avoir de l’observabilité sur ce qui fait ton observabilité.

Comment le tracing a changé notre façon de livrer

Trois habitudes en sont nées.

On rattache une identité aux traces, pas seulement des données. Une trace porte des tags et des métadonnées qui nous disent quel parcours utilisateur, quel canal et quelle configuration d’agent l’ont produite. Quand quelqu’un signale « Notis s’est emmêlé sur Telegram ce matin », c’est un filtre, pas un chantier d’archéologie.

On lit les traces avant de lire les réclamations. Un utilisateur qui signale une mauvaise réponse ne peut en général pas te dire ce qui a déraillé, parce que la défaillance est invisible de son côté. La trace, si. La plupart de nos signalements « le modèle est mauvais » se révèlent être un outil qui a renvoyé quelque chose d’inattendu, et un modèle qui a fait de son mieux avec.

On a intégré le feedback au Portal. Une route permet de noter une trace Langfuse depuis le produit, si bien qu’un pouce vers le bas sur une réponse se rattache à l’exécution exacte qui l’a produite. Un ressenti sans la trace, c’est du bruit. Un ressenti sur la trace, c’est un jeu de données.

Ce que je dirais à un autre builder d’agents

Si tu construis quoi que ce soit d’agentique, mets le tracing en place avant de faire le malin.

Le réflexe, c’est d’ajouter l’observabilité une fois que le produit marche. Mais un agent n’a pas d’état « ça marche » que tu peux figer : il a une distribution de comportements, et il faut voir cette distribution pour l’améliorer. Chaque heure passée tôt sur le tracing m’a fait économiser plusieurs heures de devinettes ensuite.

Quelques conseils pratiques :

• Encapsule le SDK, ne l’appelle pas directement. Un module, un seul endroit pour imposer le masquage, un seul endroit pour corriger un bug de threads.
• Trace l’unité de travail visible par l’utilisateur, pas la requête HTTP. Dans un agent, ce n’est pas la même chose.
• Mets des spans sur tes outils. Les appels de modèle sont le premier réflexe à tracer et rarement ce qui est cassé. C’est dans les appels d’outils que la réalité s’invite.
• Définis ton contrat de confidentialité avant d’avoir des données, parce que nettoyer après coup un backend de tracing n’a rien d’un bon week-end.

Notis est un produit dirigé par son fondateur, qui s’étend encore activement de la capture vocale vers Notion à des workflows sur des outils connectés. Une grande partie de cette expansion n’est possible que parce que je peux voir ce que l’agent a vraiment fait, étape par étape, au lieu de me disputer avec un fichier de log.

Langfuse, c’est ce qui me permet de le voir. Va y jeter un œil si tu livres des agents.