From ba9e0ab4773a9d63ecbe0669ac12b9f9623d4cd0 Mon Sep 17 00:00:00 2001
From: toto <antitbone@jefaismonrhum.sdv.fr>
Date: Thu, 5 Mar 2026 13:37:55 +0100
Subject: [PATCH] docs(architecture): update for v1.1.11 changes

- stdout sink documented as no-op (no data on stdout, operational logs on stderr)
- clickhouse sink: document full logging (INFO connect, DEBUG batch, WARN drop/retry, ERROR flush)
- architecture modules: update responsibilities for stdout and clickhouse adapters
- testing section: add StdoutSink and clickhouse logging coverage
- observability section: add info_logs, warn_logs, error_logs examples for clickhouse

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 architecture.yml | 33 +++++++++++++++++++++++++--------
 1 file changed, 25 insertions(+), 8 deletions(-)

diff --git a/architecture.yml b/architecture.yml
index fa73e93..3871501 100644
--- a/architecture.yml
+++ b/architecture.yml
@@ -356,6 +356,8 @@ outputs:
         batch asynchrones, drop en cas de saturation. Le service insère uniquement
         dans une table RAW (raw_json String, ingest_time DateTime DEFAULT now()).
         La table parsée et la vue matérialisée sont gérées en externe (DDL séparés).
+        Toutes les erreurs de connexion, de flush et de retry sont loggées :
+        INFO à la connexion, ERROR sur échec de flush, WARN sur drop/retry, DEBUG sur envoi réussi.
       dsn: clickhouse://user:pass@host:9000/db
       table: correlated_logs_http_network
       batch_size: 500
@@ -366,12 +368,12 @@ outputs:
       timeout_ms: 1000
     stdout:
       enabled: false
-      level: INFO  # DEBUG: tous les logs (y compris orphelins), INFO: seulement corrélés, WARN: corrélés seulement, ERROR: aucun
       description: >
-        Sink optionnel pour les tests/développement.
-        Le niveau de log filtre la sortie : DEBUG émet tout (y compris orphelins),
-        INFO émet uniquement les logs corrélés, WARN émet les logs corrélés seulement,
-        ERROR n'émet rien.
+        Sink no-op pour les données. Aucune donnée corrélée ou orpheline n'est
+        jamais écrite sur stdout. Ce sink existe uniquement pour satisfaire
+        l'interface CorrelatedLogSink. Les logs opérationnels du service
+        (démarrage, erreurs, métriques de débogage) sont toujours sur stderr
+        via observability.Logger, indépendamment de ce sink.
 
 correlation:
   description: >
@@ -736,11 +738,15 @@ architecture:
         - Gestion du drop_on_overflow.
         - Retry avec backoff exponentiel (MaxRetries=3).
         - API native clickhouse-go/v2 (PrepareBatch + Append + Send).
+        - Logging complet via observability.Logger (SetLogger) : INFO à la connexion,
+          DEBUG sur envoi réussi (rows/table), WARN sur drop buffer et retries,
+          ERROR sur échec de flush (périodique, batch, fermeture).
     - name: internal/adapters/outbound/stdout
       type: adapter_outbound
       responsibilities:
-        - Écriture des logs vers stdout pour débogage.
-        - Filtrage par niveau (DEBUG, INFO, WARN, ERROR).
+        - Sink no-op pour les données corrélées.
+        - Write/Flush/Close ne font rien : les données ne passent jamais par stdout.
+        - Les logs opérationnels sont sur stderr via observability.Logger (indépendant de ce sink).
     - name: internal/adapters/outbound/multi
       type: adapter_outbound
       responsibilities:
@@ -771,9 +777,10 @@ testing:
     focus:
       - CorrelationService (fenêtre, TTL, évictions, one-to-many/Keep-Alive)
       - Parsing A/B → NormalizedEvent (datagrammes JSON)
-      - ClickHouseSink (batching, retry, overflow)
+      - ClickHouseSink (batching, retry, overflow, logging erreurs/succès)
       - FileSink (réouverture sur SIGHUP)
       - MultiSink (fan-out)
+      - StdoutSink (no-op data, test stdout reste vide)
       - Config (validation, valeurs par défaut, exclude_source_ips)
       - UnixSocketSource (lecture, permissions, cleanup)
       - CorrelationMetrics (suivi des statistiques)
@@ -843,6 +850,16 @@ observability:
       - "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"
+      - "[clickhouse] DEBUG batch sent: rows=42 table=correlated_logs_http_network"
+    info_logs:
+      - "[clickhouse] INFO connected to ClickHouse: table=... batch_size=500 flush_interval_ms=200"
+    warn_logs:
+      - "[clickhouse] WARN buffer full, dropping log: table=... buffer_size=5000"
+      - "[clickhouse] WARN retrying batch insert: attempt=2/3 delay=100ms rows=42 err=connection refused"
+    error_logs:
+      - "[clickhouse] ERROR periodic flush failed: ..."
+      - "[clickhouse] ERROR batch flush failed: ..."
+      - "[clickhouse] ERROR final flush on close failed: ..."
   metrics_server:
     enabled: true
     endpoints: