LogWhispererAI/docs/specs/ingestion_script.md

Technical Specification - Log Ingestion Script (Feature 1)

Status: ✅ Completed & Approved
Sprint: 1
Author: Tech Lead
Date: 2026-04-02
Review: Sprint 1 Project Review

---

1. Overview

Uno script Bash leggero da installare sui server dei clienti che monitora i log di sistema, rileva pattern di errore critici e invia i payload via HTTP POST a un webhook n8n configurabile.

2. Requisiti Funzionali

2.1 Log Sources Monitorati

• /var/log/syslog (o /var/log/messages su RHEL-based)
• /var/log/nginx/error.log
• /var/log/postgresql/*.log

2.2 Pattern di Errore Rilevati

• FATAL
• ERROR
• OOM / Out of memory
• segfault
• disk full / No space left on device
• Connection refused
• Permission denied (in contesti critici)

2.3 Payload JSON (POST al Webhook)

{
  "client_id": "<CLIENT_ID>",
  "hostname": "<HOSTNAME>",
  "source": "/var/log/syslog",
  "severity": "critical",
  "timestamp": "2026-04-02T10:30:00Z",
  "raw_log": "Apr  2 10:30:00 server kernel: Out of memory: Kill process 1234",
  "matched_pattern": "OOM"
}

2.4 Configurazione

File di configurazione: /etc/logwhisperer/config.env

WEBHOOK_URL="https://your-n8n-instance.com/webhook/logwhisperer"
CLIENT_ID="unique-client-uuid"
LOG_SOURCES="/var/log/syslog,/var/log/nginx/error.log"
POLL_INTERVAL=5
MAX_LINE_LENGTH=2000

3. Requisiti Non Funzionali

3.1 Safety First (Metodo Sacchi)

• Read-only: Lo script NON scrive mai sui log monitorati
• Graceful degradation: Se un file di log non esiste, lo salta silenziosamente
• Rate limiting: Max 1 alert/30s per source per evitare flood
• No root escalation: Funziona con permessi di lettura sui log (gruppo adm)

3.2 Little Often

• Polling interval configurabile (default: 5s)
• Tiene traccia dell'ultima posizione letta (offset) per ogni file
• Non ricarica mai righe già processate

3.3 Double Check

• Verifica connettività al webhook prima di inviare
• Retry con backoff esponenziale (max 3 tentativi)
• Log locale di debug in /var/log/logwhisperer/debug.log

4. Architettura

┌─────────────────────────────────────────────┐
│           LogWhisperer Agent                │
│                                             │
│  ┌─────────┐  ┌──────────┐  ┌────────────┐ │
│  │ File    │  │ Pattern  │  │ HTTP       │ │
│  │ Tailing │─>│ Matcher  │─>│ Dispatcher │ │
│  └─────────┘  └──────────┘  └────────────┘ │
│       ^                           |         │
│       │     ┌──────────┐          |         │
│       └─────│ Offset   │<─────────┘         │
│             │ Tracker  │   (on success)     │
│             └──────────┘                     │
└─────────────────────────────────────────────┘

5. Struttura File

scripts/
  logwhisperer.sh          # Script principale
  install.sh               # Script di installazione (setup config, systemd)
tests/
  conftest.py
  test_logwhisperer.py     # Test Python con subprocess
docs/
  specs/
    ingestion_script.md    # Questo file

6. Criteri di Accettazione

• Lo script legge da almeno 2 source di log configurabili
• Rileva pattern di errore (case-insensitive)
• Invia POST JSON al webhook con payload corretto
• Gestisce retry su fallimento HTTP
• Non blocca il sistema se il webhook è down
• Test Python passano con pytest
• Script installabile con un solo comando

7. Note di Sicurezza

• Il CLIENT_ID è un UUID v4 generato in fase di installazione
• Il webhook URL deve essere HTTPS
• Nessuna credenziale hardcoded nello script
• I log di debug non contengono dati sensibili

8. Dipendenze

• Bash 4.0+
• curl (già presente su qualsiasi server Linux)
• date (GNU coreutils)
• sha256sum o md5sum (per deduplicazione opzionale)
• Nessuna dipendenza Python lato server (solo lato test)