Langfuse : la fiche technique

À quoi ça sert (le pitch en 30 secondes)

Langfuse est l'APM des applications LLM (open-source, auto-hébergeable). Pour chaque interaction il capture la hiérarchie complète :

Trace  « extract.{request_id} »            ← une requête de bout en bout
 ├─ Span  « node.matcher_fast »  240 ms    ← une étape (node LangGraph)
 ├─ Generation « structurer.extract »      ← UN appel LLM :
 │     prompt EXACT envoyé, réponse, modèle, tokens in/out, coût, latence
 └─ Event « COPILOT_TURN_TRUNCATED »       ← un fait notable

Ce que ça débloque concrètement : relire le prompt exact qui a produit une mauvaise réponse (le « stack trace » du LLM), suivre coûts et tokens par feature/tenant/modèle, voir la latence par node du pipeline, et rejouer une conversation entière via les sessions. Sans ça, débugger un agent = archéologie dans les logs.

Les concepts, mappés sur le projet

• Session = un thread de conversation copilot (session_id = thread_id, avec user_id) : toute la conversation regroupée dans l'UI ;
• Generation = une itération de la boucle ReAct, avec usage_details (tokens + lecture cache — on vérifie que le prompt caching du module 4 fonctionne vraiment !) ;
• Span = un node LangGraph ou l'exécution d'un tool ;
• l'API v3+ : client.start_observation(as_type="agent"|"span"|"generation"|"tool"|"event") — le projet passe par une classe LangfuseObserver maison plutôt que les décorateurs @observe, pour garder le contrôle.

Les trois patterns d'intégration à retenir

1. Best-effort, toujours : Langfuse down → un observer Noop prend la place ; les flush partent via asyncio.to_thread. L'observabilité ne casse jamais la prod ni ne bloque l'event loop ;
2. Redactor + Sampler : les inputs sont scrubés (PII, prix) avant envoi — les traces vivent hors de la base RLS, elles n'ont pas le droit d'être plus bavardes qu'elle ; et on n'échantillonne pas forcément 100 % du trafic ;
3. Le piège async (ADR-0013) : la propagation de contexte OTel (start_as_current_span) se perd aux points de suspension de LangGraph (chaque await peut changer de contexte). Solution du projet : porter la trace courante dans des ContextVar explicites (_CURRENT_PIPELINE_TRACE, _CURRENT_NODE_SPAN) — la propagation manuelle, fiable par construction.

Les évolutions récentes (l'outil vit)

Deux progrès depuis le premier état des lieux :

• les datasets d'éval sont maintenant utilisés : le harness d'éval (module 3, étude de cas) pousse chaque run comme dataset run comparable dans l'UI — les scores d'un fix se lisent côte à côte avec la baseline ;
• les coûts sont devenus réels : le suivi de coûts couvre désormais le cache de prompt (lu ≠ facturé plein tarif), l'OCR et le rerank — pas seulement les tokens du LLM principal. Une trace qui ignore 30 % de la facture ment ; le multi-provider (LLM + OCR + rerank) exige une comptabilité par fournisseur.

Restent inutilisés : le prompt management (versionner/itérer les prompts sans redéploiement — la porte d'entrée naturelle quand les consignes par tenant arriveront) et les scores automatiques.