SYS_PQ_2 — Procédure de télémétrie des appels LLM

Procédure légère. Le DDL et le détail nœud-par-nœud vivent dans 07 / 90_Reference_SQL/. [CORPUS]

Objet

Décrire comment chaque appel LLM est tracé de manière souveraine, append-only et non bloquante, et comment la réponse OpenRouter est mappée vers les colonnes de telemetrie.appels_llm. [CORPUS]

Domaine d'application

Tout appel passant par agent_call (cf. SYS_PRO_1). Les appels d'ingestion Mistral (OCR/Voxtral) sont hors périmètre (non télémétrés — ce ne sont pas des agents). [CORPUS]

Références

Table : telemetrie.appels_llm — DDL complet 90_Reference_SQL/lot6g0_telemetrie_appels_llm.sql ; description 07 §B1bis. [CORPUS]
Workflow : log_llm_call — 07 §B2.12 (INSERT unique $1..$18, onError:continueRegularOutput). [CORPUS]
ADR-029 — souveraineté, capture synchrone non bloquante, coût natif. [CORPUS]
ADR-036 — toute table via script versionné idempotent. [CORPUS]
P-6g0-1 — reasoning_tokens jamais par soustraction. [CORPUS]
Pas de norme externe applicable. [STANDARD]

Définitions

Append-only : insertion seule ; pas d'UPDATE/DELETE (rôle n8n_user = SELECT+INSERT only). « Résilience > intégrité » : aucune FK dure ne doit pouvoir bloquer un log. [CORPUS]
IDENTITY : id bigint GENERATED ALWAYS AS IDENTITY — écriture manuelle de l'id rejetée par Postgres. [CORPUS]
Axes analytiques : dossier_id, agent_key, code_direction, task_type (4 axes de groupement). [CORPUS]

Responsabilités (RACI)

Activité	agent_call	log_llm_call	Postgres (n8n_user)	Gérant
Assembler le payload (mapping réponse)	R	C	—	—
Exécuter l'INSERT	A	R	C	—
Garantir le non-blocage (fire-and-forget)	R	C	—	—
Maintenir le DDL / droits / index	C	—	C	R/A
Exploiter la donnée (dashboards)	—	—	—	R (+ agent Pilote)

Déroulement (qui/quoi/quand/où)

agent_call assemble l'objet plat (18 champs) à partir de la réponse OpenRouter — mapping ci-dessous. [CORPUS]
agent_call appelle log_llm_call (Execute Workflow), après avoir construit la sortie depuis Parse response (jamais depuis le log). [CORPUS]
log_llm_call exécute l'INSERT paramétré ; id/ts posés par Postgres ; onError:continueRegularOutput. [CORPUS]
Sur échec LLM, le même log_llm_call est appelé avec success=false, tokens/coût null (cf. SYS_PRO_5). [CORPUS]

Mapping réponse OpenRouter → colonnes (règle d'or de la procédure)

Colonne	Source	Note
`prompt_tokens` / `completion_tokens` / `total_tokens`	`usage.*` directs	`total = prompt + completion` [CORPUS]
`reasoning_tokens`	`usage.completion_tokens_details.reasoning_tokens`	sous-ensemble de completion ; jamais `total−in−out` (P-6g0-1) [CORPUS]
`cache_read_tokens`	`usage.prompt_tokens_details.cached_tokens`	[CORPUS]
`cache_write_tokens`	best-effort	null si absent [CORPUS]
`cost_usd`	`usage.cost`	natif, jamais recalculé [CORPUS]
`openrouter_generation_id`	`response.id`	réconciliation a posteriori [CORPUS]
`latency_ms`	`Date.now() − t0` autour du nœud HTTP	inclut le round-trip réel [CORPUS]
`agent_key` / `code_direction` / `model` / `resolved_from_mode` / `provider`	issus de `prepare_agent_call`	[CORPUS]
`task_type` / `dossier_id`	portés par `agent_call` depuis l'appelant	[CORPUS]
`success` / `error`	`true`/null (succès) ; `false`/message (échec)	[CORPUS]

Enregistrements associés

telemetrie.appels_llm (cf. SYS_FQ_2). [CORPUS]

Annexes

Index : (ts), (code_direction, ts), (agent_key, ts), (task_type, ts), (dossier_id). [CORPUS]
Droits : n8n_user SELECT+INSERT + USAGE séquence ; owner admin. [CORPUS]