Aller au contenu

Observabilité

Logs structurés

Tous les composants utilisent le logger logging standard avec préfixe
DEBUG: pour faciliter le filtrage. Les champs récurrents :

Champ Description
transcript_id Identifiant de la transcription en cours.
user_id Propriétaire de la transcription.
stage Étape du pipeline (extraction, rag_enrichment, llm, geo, scoring, gate, persist).
mode RAG_ENHANCED ou CONTEXT_FREE.
analysis_version Version logique active.
retry_count Numéro de tentative pour le worker.
outcome Résultat structuré (succès, raison de rejet, code d'erreur).

Métriques Prometheus

Préfixe : reliability_ (sauf indication contraire).

Worker

Nom Type Labels Mesure
worker_messages_processed_total Counter outcome ∈ success|failure|lock_busy|dlq Messages traités.
worker_processing_duration_ms Histogram — Latence par message.
worker_lock_acquired_total Counter outcome ∈ acquired|busy Contention sur le lock.
worker_retry_scheduled_total Counter — Retries planifiés.
worker_retry_promoted_total Counter — Retries promus vers le stream principal.
worker_dlq_send_total Counter — Messages envoyés en DLQ.
worker_drain_timeout_total Counter — Timeouts d'arrêt gracieux.

Validation déterministe

Nom Type Labels Mesure
suggestions_filtered_by_{rule} Counter rule ∈ type_known, identity, blacklist, confidence_min, levenshtein, acronym_initials, typo_levenshtein Rejets par règle.

Pipeline multi-signal

Nom Type Labels Mesure
reliability_v5_llm_call_total Counter outcome ∈ correct|abstain|conflict|json_schema_violation Appels au raisonneur.
reliability_v5_llm_abstain_total Counter reason ∈ insufficient_evidence|json_schema_violation|conflict Détail des abstentions.
reliability_v5_fused_score Histogram — Distribution du score fusionné.
reliability_v5_gate_decisions_total Counter action, reason Décisions du gate.
reliability_v5_gate_threshold_distance Histogram — Distance fused_score - threshold.
reliability_v5_wikidata_boost_applied Counter outcome ∈ applied|skipped_no_qid|disabled|name_mismatch Application du boost Wikidata.

Géographie

Nom Type Labels Mesure
geo_lookup_total Counter source ∈ DISABLED|CACHE|PHOTON|ABSTAIN|TIMEOUT|ERROR|FILTERED Lookups Photon.
geo_latency_ms Histogram — Latence Photon.
geo_score Histogram — Distribution des scores géographiques.
wikidata_lookup_total Counter outcome ∈ cache_hit|sparql_hit|not_found|timeout|error Lookups Wikidata.
wikidata_latency_ms Histogram — Latence Wikidata.

Mémoire des corrections

Nom Type Labels Mesure
correction_memory_lookups_total Counter outcome Recherches du lecteur.
correction_memory_top_score Histogram — Score cosine top-1.
correction_memory_writes_total Counter outcome ∈ success|dedupe_hit|validation_error|qdrant_error|… Opérations d'écriture.

Tableaux de bord recommandés

Vue santé du worker

  • rate(reliability_worker_messages_processed_total[5m]) par outcome.
  • Ratio lock_busy / acquired — détecte les boucles de retry concurrentielles.
  • Quantile 95 de reliability_worker_processing_duration_ms.
  • Profondeur estimée des streams (reliability:events, :retry, :dlq).

Vue qualité du pipeline

  • Répartition reliability_v5_gate_decisions_total par (action, reason).
  • Histogramme reliability_v5_fused_score superposé au seuil.
  • Taux d'abstention LLM : reliability_v5_llm_abstain_total / reliability_v5_llm_call_total.
  • Top 10 règles de filtrage par volume : suggestions_filtered_by_*.

Vue dépendances externes

  • Latence et taux d'erreurs Photon, Wikidata, LLM (par provider).
  • Taux de hit cache Redis pour Photon et Wikidata.
  • Taux d'application du boost Wikidata.

Troubleshooting

Le pipeline ne démarre pas

  1. Vérifier RELIABILITY_BACKEND_V1_ENABLED=true.
  2. Vérifier que Redis est joignable et que le consumer group existe
    (XINFO GROUPS reliability:events).
  3. Vérifier le bootstrap Qdrant en cas d'utilisation de la mémoire de
    corrections — un statut DIM_MISMATCH empêche le démarrage.

Toutes les suggestions sont rejetées par le gate

  1. Inspecter reliability_v5_gate_decisions_total{reason="llm_abstain"} : si
    dominant, la qualité de la liste canonique est probablement insuffisante.
  2. Inspecter reliability_v5_gate_decisions_total{reason="low_fused_score"} :
    ajuster RELIABILITY_V5_GATE_THRESHOLD ou les pondérations par type.
  3. Vérifier la disponibilité du provider LLM primaire (logs).

Saturation des retries

  1. Profondeur du stream reliability:events:retry > seuil opérationnel.
  2. Identifier le provider en cause (logs provider et error).
  3. Si nécessaire, basculer temporairement RELIABILITY_LLM_PRIMARY sur le
    fallback.

La DLQ se remplit

  1. GET /api/reliability/dlq/stats pour mesurer le volume.
  2. GET /api/reliability/dlq/list pour échantillonner les erreurs.
  3. Corriger la cause racine, puis POST /api/reliability/dlq/reprocess entrée
    par entrée.

Locks bloqués

  1. Repérer le pic de reliability_worker_lock_acquired_total{outcome="busy"}.
  2. Inspecter les clés Redis reliability_lock:* et leur TTL.
  3. Un lock orphelin expire automatiquement après
    RELIABILITY_LOCK_TTL_SECONDS ; la libération anticipée n'est jamais
    nécessaire car le script Lua évite les libérations croisées.

Snapshots de score manquants

  1. Vérifier que la transcription a au moins une suggestion persistée.
  2. Vérifier la règle d'idempotence : si aucun changement n'est survenu depuis
    le dernier snapshot, aucun INSERT n'est produit (comportement attendu).
  3. Vérifier les logs du worker pour détecter une erreur dans
    recalc_transcript_score.