SYS_PRO_2 — Télémétrie et observabilité des appels LLM

Manuel LÉGER. Processus implémenté (Lots 6g·0 / 6g / 6h). Source du quoi : 07_Reference_Systeme.md §B1bis (table) + §B2.12 (log_llm_call). Source du pourquoi : ADR-029, ADR-034. [CORPUS]

Objet et finalité

Capturer, pour chaque appel LLM (succès ou échec), une trace structurée et souveraine — coût, vitesse, tokens, attribution (agent / Direction / dossier / nature de tâche) — persistée dans Postgres (telemetrie.appels_llm). [CORPUS]

Finalité : alimenter le pilotage des coûts (dashboard 8bis-A, UC-E01), l'audit Opus-vs-Sonnet par tentative, et la réconciliation a posteriori avec OpenRouter. La télémétrie est souveraine (indépendante de tout SaaS d'observabilité) et non bloquante (elle ne casse jamais le flux métier — fire-and-forget). [CORPUS]

Frontière (cf. Recueil_Cas_Usage.md Famille E) : la télémétrie est de la donnée opérationnelle (telemetrie), pas du corpus de connaissance. Elle n'entre pas dans la taxonomie d'ingestion. [CORPUS]

Pilote

Direction pilote : SYS — Système.
Acteur : sub-workflow log_llm_call (write DAL — INSERT unique append-only), appelé en synchrone non bloquant depuis agent_call. Pas d'agent LLM. Exploitation aval : agent Pilote (P29, DJC/transverse) et dashboard. [CORPUS]

Déclencheurs (entrées)

Appel Execute Workflow de log_llm_call depuis agent_call :
- en fin de branche succès (Build log payload) ; [CORPUS]
- en fin de branche d'échec (Build error log payload, success=false, tokens/coût null). [CORPUS]
INPUT (objet plat = colonnes, snake_case) : agent_key, code_direction, task_type, dossier_id, model, provider, resolved_from_mode, prompt_tokens, completion_tokens, reasoning_tokens, cache_read_tokens, cache_write_tokens, total_tokens, cost_usd, openrouter_generation_id, latency_ms, success, error. [CORPUS]

Sorties et livrables

1 ligne insérée dans telemetrie.appels_llm (id IDENTITY + ts DEFAULT now() posés par Postgres). [CORPUS]
OUTPUT workflow : { logged:true } (best-effort ; un échec d'INSERT n'est pas remonté à l'appelant — fire-and-forget). [CORPUS]
Livrables aval : dashboards coût/vitesse/volume (8bis-A) ; résumés d'activité (agent Pilote). [CORPUS]

Acteurs

Acteur	Rôle	Nature
`agent_call`	source du log (assemble le payload depuis la réponse OpenRouter)	sub-workflow [CORPUS]
`log_llm_call`	write DAL — INSERT unique paramétré `$1..$18`	sub-workflow [CORPUS]
`telemetrie.appels_llm`	table append-only (20 colonnes)	Postgres [CORPUS]
credential `Postgres Jarfish_db n8n_user`	rôle append-only (SELECT+INSERT only)	n8n credential [CORPUS]
Dashboard 8bis-A / agent Pilote (P29)	consommateurs analytiques	aval [CORPUS]

Logigramme (étapes macro)

[agent_call] Build log payload (succès)  ─┐
[agent_call] Build error log payload (échec) ─┴→ Call log_llm_call (fire-and-forget)
                                                    │
                                              [log_llm_call] Postgres INSERT (18 colonnes, $1..$18)
                                                    │   onError:continueRegularOutput
                                              [log_llm_call] Sortie { logged:true }
                                                    ▼
                                       telemetrie.appels_llm  (+id IDENTITY, +ts now())
                                                    ▼
                          (aval) dashboard coût/vitesse/tokens — group by task_type/dossier_id/code_direction

Détail : 07_Reference_Systeme.md §B2.12. [CORPUS]

Procédures et instructions rattachées

SYS_PQ_2 — Procédure de télémétrie (mapping réponse→colonnes, append-only, droits).
SYS_FQ_2 — Formulaire : table telemetrie.appels_llm (structure complète des 20 colonnes — livrable central de ce processus).
(Instruction de mapping intégrée dans SYS_PQ_2 ; pas d'IQ dédiée — la logique est dans agent_call. Voir Roadmap.)

Interfaces amont/aval (handoffs)

Amont : SYS_PRO_1 (Orchestration) — fournit le payload. [CORPUS]
Aval :
- Lecture analytique par le dashboard 8bis-A (Tremor sur Postgres, zéro migration). [CORPUS]
- Agent Pilote (P29) : résumés d'activité, alertes proactives (mission en attente labo > seuil) — lit registre_* + telemetrie. [CORPUS]
- Réconciliation coût : openrouter_generation_id → GET /generation?id= côté OpenRouter. [CORPUS]
Réservé / différé : trace_id (colonne langfuse_trace_id côté productions_agents) = null v0, prêt pour rebranchement Langfuse Cloud sans migration. [CORPUS]

Indicateurs (KPI)

KPI	Définition	Source
Coût total / période	`sum(cost_usd)` sur fenêtre	`telemetrie.appels_llm` [CORPUS]
Coût par Direction / dossier / task_type	`sum(cost_usd)` group by axe	idem [CORPUS]
Volume d'appels / jour	`count(*)` group by jour	idem [CORPUS]
Part reasoning	`sum(reasoning_tokens)/sum(completion_tokens)`	idem [STANDARD]
Taux de perte de log	appels sans ligne (estimé via compteur `agent_call` vs lignes)	croisement [À CONFIRMER]

Enregistrements

telemetrie.appels_llm — l'enregistrement de référence (append-only, IDENTITY, 20 colonnes). [CORPUS]

Cas d'usage rattachés (UC-* du Recueil + nouveaux)

UC-E01 — Dashboard coûts LLM (coût/vitesse/tokens par modèle / task_type / dossier). [CORPUS]
UC-E02 — Résumé d'activité hebdo (agent Pilote, croise télémétrie + registres). [CORPUS]
UC-SYS-02 (nouveau) — Auditer le surcoût d'une relance Opus vs Sonnet sur une même tentative (via task_type/dossier_id + cost_usd). [CORPUS]

Roadmap (PQ/IQ/FQ restant à développer)

SYS_IQ_2_1 — Instruction « mapping réponse OpenRouter → colonnes » (aujourd'hui dans agent_call/Build log payload ; à externaliser en instruction si réutilisé). [CORPUS]
Axe qualité différé : modélisation d'un score qualité au niveau production/dossier (Lots 9+), hors appels_llm (un appel est trop atomique). → nouveau FQ quand câblé. [CORPUS]
Au cutover Postgres (ADR-033), seule la cible de log_llm_call bouge ; l'INSERT et les KPI restent — à acter dans 09. [CORPUS]