# Technical Specification - Log Ingestion Script (Feature 1)

**Status:** ✅ Completed & Approved  
**Sprint:** 1  
**Author:** Tech Lead  
**Date:** 2026-04-02  
**Review:** [Sprint 1 Project Review](../reviews/sprint1_review.md)  

---

## 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)
```json
{
  "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`
```bash
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/
  __init__.py
  test_logwhisperer.py     # Test Python con subprocess
docs/
  specs/
    ingestion_script.md    # Questo file
```

## 6. Criteri di Accettazione

- [x] Lo script legge da almeno 2 source di log configurabili
- [x] Rileva pattern di errore (case-insensitive)
- [x] Invia POST JSON al webhook con payload corretto
- [x] Gestisce retry su fallimento HTTP
- [x] Non blocca il sistema se il webhook è down
- [x] Test Python passano con pytest
- [x] 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)