3a455e48d2
- Add MCP servers documentation (n8n, context7, sequential-thinking) - Update README.md with complete project structure and requirements.txt - Transform agents.md into comprehensive agent staff catalog (9 agents) - Update CHANGELOG.md with [Unreleased] MCP entries - Fix ingestion_script.md acceptance criteria checkboxes - Add .opencode/opencode.json to .gitignore for security - Include new agent configs: n8n_specialist_agent, context_auditor_agent - Include new skill playbooks: n8n_automation, context7_documentation Security: API credentials in .opencode/opencode.json are now gitignored
128 lines
4.3 KiB
Markdown
128 lines
4.3 KiB
Markdown
# 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)
|