feat: observability, IP filtering, stdout/clickhouse fixes (v1.1.11)

- feat(observability): metrics server with /metrics and /health endpoints
- feat(observability): correlation metrics (events, success/failed, reasons, buffers)
- feat(correlation): IP exclusion filter (exact IPs and CIDR ranges)
- feat(correlation): pending orphan delay for late-arriving B events
- fix(stdout): sink is now a no-op for data; JSON must never appear on stdout
- fix(clickhouse): all flush errors were silently discarded, now properly logged
- fix(clickhouse): buffer overflow with DropOnOverflow now logged at WARN
- fix(clickhouse): retry attempts logged at WARN with attempt/delay/error context
- feat(clickhouse): connection success logged at INFO, batch sends at DEBUG
- feat(clickhouse): SetLogger() for external logger injection
- test(stdout): assert stdout remains empty for correlated and orphan logs
- chore(rpm): bump version to 1.1.11, update changelog
- docs: README and architecture.yml updated

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

architecture.yml

@@ -13,9 +13,16 @@ service:
     HTTP Keep-Alive : un log réseau peut être corrélé à plusieurs logs HTTP
     successifs (stratégie 1‑à‑N). La rétention en mémoire est bornée par des
     tailles de caches configurables et un TTL dynamique pour la source B. Le
-    service émet toujours les événements A même lorsqu’aucun événement B n’est
-    disponible, n’émet jamais de logs B seuls, et pousse les résultats vers
+    service émet toujours les événements A même lorsqu'aucun événement B n'est
+    disponible, n'émet jamais de logs B seuls, et pousse les résultats vers
     ClickHouse et/ou un fichier local.
+    
+    Fonctionnalités de débogage incluses :
+    - Serveur de métriques HTTP (/metrics, /health)
+    - Logs DEBUG détaillés avec raisons des échecs de corrélation
+    - Filtrage des IPs source (exclude_source_ips)
+    - Scripts de test (Bash et Python)
+    - Métriques : événements reçus, corrélations, échecs par raison, buffers, orphelins
 
 runtime:
   deployment:
@@ -276,6 +283,20 @@ config:
         # Augmenté à 120s pour supporter les sessions HTTP Keep-Alive longues.
         network_ttl_s: 120
 
+      # Filtrage des IPs source à exclure (optionnel)
+      exclude_source_ips:
+        - 10.0.0.1           # IP unique
+        - 172.16.0.0/12      # Plage CIDR
+        # Les événements depuis ces IPs sont silencieusement ignorés
+
+    # Serveur de métriques HTTP (optionnel, pour débogage et monitoring)
+    metrics:
+      enabled: false
+      addr: ":8080"  # Adresse d'écoute du serveur HTTP
+      # Endpoints:
+      #   GET /metrics - Retourne les métriques de corrélation en JSON
+      #   GET /health  - Health check
+
 inputs:
   description: >
     Deux flux de logs JSON via sockets Unix datagram (SOCK_DGRAM). Chaque datagramme
@@ -734,6 +755,9 @@ architecture:
       type: infrastructure
       responsibilities:
         - Logger structuré avec niveaux (DEBUG, INFO, WARN, ERROR).
+        - CorrelationMetrics : suivi des statistiques de corrélation.
+        - MetricsServer : serveur HTTP pour exposition des métriques (/metrics, /health).
+        - Traçage des événements exclus (exclude_source_ips).
         - Logs pour : événements reçus, corrélations, orphelins, buffer plein.
 
 testing:
@@ -750,13 +774,16 @@ testing:
       - ClickHouseSink (batching, retry, overflow)
       - FileSink (réouverture sur SIGHUP)
       - MultiSink (fan-out)
-      - Config (validation, valeurs par défaut)
+      - Config (validation, valeurs par défaut, exclude_source_ips)
       - UnixSocketSource (lecture, permissions, cleanup)
+      - CorrelationMetrics (suivi des statistiques)
+      - MetricsServer (endpoints /metrics et /health)
   integration:
     description: >
       Tests d'intégration limités. Le flux complet A+B → corrélation → sinks est
       testé via des tests unitaires avec mocks. ClickHouse est mocké (pas de tests
       avec vrai ClickHouse). Scénarios Keep-Alive testés dans correlation_service_test.go.
+      Scripts de test fournis : scripts/test-correlation.sh et scripts/test-correlation-advanced.py.
 
 docker:
   description: >
@@ -798,3 +825,109 @@ docker:
     - path: Dockerfile.package
       description: Packaging RPM multi-distros (el8, el9, el10) avec scripts post/preun/postun.
 
+observability:
+  description: >
+    Le service inclut des fonctionnalités complètes de débogage et de monitoring
+    pour diagnostiquer les problèmes de corrélation et surveiller les performances.
+  logging:
+    levels:
+      - DEBUG: Tous les événements reçus, tentatives de corrélation, raisons des échecs
+      - INFO: Événements corrélés, démarrage/arrêt du service
+      - WARN: Orphelins émis, buffer plein, TTL expiré
+      - ERROR: Erreurs de parsing, échecs de sink, erreurs critiques
+    debug_logs:
+      - "event received: source=A src_ip=192.168.1.1 src_port=8080 timestamp=..."
+      - "processing A event: key=192.168.1.1:8080 timestamp=..."
+      - "correlation found: A(src_ip=... src_port=... ts=...) + B(src_ip=... src_port=... ts=...)"
+      - "A event has no matching B key in buffer: key=..."
+      - "A event has same key as B but outside time window: key=... time_diff=5s window=10s"
+      - "event excluded by IP filter: source=A src_ip=10.0.0.1 src_port=8080"
+      - "TTL reset for B event (Keep-Alive): key=... new_ttl=120s"
+  metrics_server:
+    enabled: true
+    endpoints:
+      - path: /metrics
+        method: GET
+        description: Retourne les métriques de corrélation au format JSON
+        response_example: |
+          {
+            "events_received_a": 1542,
+            "events_received_b": 1498,
+            "correlations_success": 1450,
+            "correlations_failed": 92,
+            "failed_no_match_key": 45,
+            "failed_time_window": 23,
+            "failed_buffer_eviction": 5,
+            "failed_ttl_expired": 12,
+            "failed_ip_excluded": 7,
+            "buffer_a_size": 23,
+            "buffer_b_size": 18,
+            "orphans_emitted_a": 92,
+            "keepalive_resets": 892
+          }
+      - path: /health
+        method: GET
+        description: Health check
+        response_example: |
+          {"status":"healthy"}
+  metrics_tracked:
+    events_received:
+      - events_received_a: Nombre d'événements HTTP (source A) reçus
+      - events_received_b: Nombre d'événements réseau (source B) reçus
+    correlations:
+      - correlations_success: Corrélations réussies
+      - correlations_failed: Échecs de corrélation
+    failure_reasons:
+      - failed_no_match_key: Clé src_ip:src_port non trouvée dans le buffer
+      - failed_time_window: Événements hors fenêtre temporelle
+      - failed_buffer_eviction: Buffer plein, événement évincé
+      - failed_ttl_expired: TTL du événement B expiré
+      - failed_ip_excluded: Événement exclu par filtre IP (exclude_source_ips)
+    buffers:
+      - buffer_a_size: Taille actuelle du buffer HTTP
+      - buffer_b_size: Taille actuelle du buffer réseau
+    orphans:
+      - orphans_emitted_a: Orphelins A émis (sans correspondance B)
+      - orphans_emitted_b: Orphelins B émis (toujours 0, policy: network_emit=false)
+      - orphans_pending_a: Orphelins A en attente (délai avant émission)
+      - pending_orphan_match: B a corrélé avec un orphelin A en attente
+    keepalive:
+      - keepalive_resets: Resets TTL pour mode Keep-Alive (one-to-many)
+  troubleshooting:
+    description: >
+      Guide de diagnostic basé sur les métriques et logs
+    common_issues:
+      - symptom: failed_no_match_key élevé
+        cause: Les logs A et B n'ont pas le même src_ip + src_port
+        solution: Vérifier que les deux sources utilisent la même combinaison IP/port
+      - symptom: failed_time_window élevé
+        cause: Timestamps trop éloignés (> time_window.value)
+        solution: Augmenter correlation.time_window.value ou synchroniser les horloges (NTP)
+      - symptom: failed_ttl_expired élevé
+        cause: Les événements B expirent avant corrélation
+        solution: Augmenter correlation.ttl.network_ttl_s
+      - symptom: failed_buffer_eviction élevé
+        cause: Buffers trop petits pour le volume de logs
+        solution: Augmenter correlation.buffers.max_http_items et max_network_items
+      - symptom: failed_ip_excluded élevé
+        cause: Traffic depuis des IPs configurées dans exclude_source_ips
+        solution: Vérifier la configuration, c'est normal si attendu
+      - symptom: orphans_emitted_a élevé
+        cause: Beaucoup de logs A sans correspondance B
+        solution: Vérifier que la source B envoie bien les événements attendus
+  test_scripts:
+    - name: scripts/test-correlation.sh
+      description: Script Bash pour tester la corrélation avec des événements synthétiques
+      features:
+        - Envoi de paires A+B avec mêmes src_ip:src_port
+        - Vérification des métriques avant/après
+        - Options: -c (count), -d (delay), -v (verbose), -m (metrics-url)
+    - name: scripts/test-correlation-advanced.py
+      description: Script Python avancé avec multiples scénarios de test
+      features:
+        - Basic test: corrélations simples
+        - Time window test: vérifie l'expiration de la fenêtre temporelle
+        - Different IP test: vérifie non-corrélation avec IPs différentes
+        - Keep-Alive test: vérifie le mode one-to-many
+        - Métriques en temps réel
+