The wiki becomes a guide for the people who use Khaemhat: a new "Guida all'uso" page walks from sign-in to an invoice sent by e-mail, and Vendite is rewritten around the real screens of 0.5.0 (radars, document mask, Crea …, deferred invoicing, print preview, mail). Primi passi, Dati di esempio, Allegati, Log and Impostazioni describe what this version does, including the SMTP variables. README.md turns into the installation guide for developers: prerequisites, run-dev, tests with PostgreSQL, migrations, image and wiki publishing. The engine now writes confirmations, changes of state and deletions to the Documents log section, the last step of #53. ADR 0034 records the print and mail decisions; CHANGELOG 0.5.0 and STATUS close the milestone. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
7.4 KiB
Log
Stato: parziale · Ultima revisione: 2026-11-11 · Versione software: 0.2.0 (milestone M2) Modulo di licenza: CORE · Livello richiesto: amministratore · Specifica: SPEC §7.3, §9.5, §12.7
Nella versione 0.2.0 il log è scritto nel database di sistema (
sys_log) con sezione, livello, utente, azienda e identificativo di traccia (headerX-Trace-Id), oltre che su console in JSON; la retention per livello gira ogni notte. La schermata Log con filtri e regole di avviso arriva in M12: fino ad allora si legge il log del container.
A cosa serve
Il log applicativo registra ciò che succede in Khaemhat: accessi, documenti emessi, invii SDI, backup, attività programmate, chiamate API, errori. Serve all'amministratore per capire cosa è successo, quando, a chi e perché, e per ritrovare un errore segnalato da un utente tramite il suo codice errore.
Dove si trova
Amministrazione → Log (titolo della pagina: Log applicativo).
Schermata
Mockup 084 — a sinistra le sezioni con i contatori, in alto la barra dei filtri, al centro gli eventi della sezione SDI / e-invoicing (ora, livello, origine, messaggio, utente, azienda, traccia), in basso il Dettaglio evento; in alto a destra il riepilogo delle ultime 24 ore, Esporta CSV e Regole di avviso (anteprima ridotta)
Come è fatto il log
Ogni evento viene scritto in due posti:
- sull'output standard del container in formato JSON, una riga per evento (visibile con
docker logs); - nel database di sistema (tabella
sys_log), da cui legge questa pagina.
Il livello minimo sull'output standard si imposta con la variabile KHAEMHAT_LOG_LEVEL (predefinito
Information); nel database vale la retention per livello (vedi sotto).
Ogni evento contiene: data e ora, livello, sezione, origine (componente che l'ha scritto), messaggio,
eventuale eccezione, utente, azienda, traccia (trace_id), richiesta, entità e identificativo collegati, dati
aggiuntivi.
Livelli
| Livello | Sigla | Uso |
|---|---|---|
| Errore | ERR | operazione fallita (es. fattura scartata dallo SDI) |
| Avviso | WRN | situazione da controllare (es. file duplicato ignorato, accesso da dispositivo sconosciuto) |
| Informazione | INF | operazione riuscita (es. XML generato, notifiche lette) |
| Debug | DBG | dettagli tecnici per la diagnosi |
Sezioni
Ogni modulo scrive nella propria sezione. Il pannello a sinistra le elenca con il numero di eventi:
| Sezione | Cosa contiene |
|---|---|
| Sistema | avvio, arresto, configurazione |
| Autenticazione | accessi, errori di password, blocchi, 2FA, nuovi dispositivi |
| Database | connessioni, manutenzione |
| Migrazioni | migrazioni applicate e loro esito |
| Documenti | conferma ed emissione con il numero assegnato, chiusura, riapertura, annullamento, eliminazione delle bozze (da 0.5.0) |
| Contabilità | registrazioni, liquidazioni, chiusure |
| Magazzino | movimenti, ricostruzioni |
| SDI / e-invoicing | generazione XML, invii, notifiche, scarti |
| CRM | lead, opportunità, attività |
| Automazioni | esecuzione delle regole |
| Attività programmate | inizio, fine, durata, esito di ogni esecuzione |
| Backup | backup, copie remote, verifiche, ripristini |
| API / MCP | chiamate API e strumenti MCP |
| E-mail / PEC | invii e letture di posta: da 0.5.0 ogni messaggio messo in coda, inviato, ritentato o fallito, con la risposta del server SMTP |
| Integrazioni | VIES, cambi BCE, intermediari SDI |
| UI / circuiti | errori dell'interfaccia con lo stack completo |
| Prestazioni | query oltre 500 ms, richieste lente, garbage collection |
Come si usa
Cercare un evento
- Scegli la sezione a sinistra (oppure Tutte).
- Usa la barra dei filtri:
- testo libero (es. un numero di documento o un codice di scarto come
00311); - Periodo (es. Ultime 24 ore);
- Livello (es. Avvisi ed errori);
- Azienda e Utente;
- Traccia (il
trace_id); - origine ed entità collegata. I filtri attivi compaiono come chip (es. Sezione: SDI x).
- testo libero (es. un numero di documento o un codice di scarto come
- Clicca un evento per aprirne il Dettaglio.
Il dettaglio dell'evento
Mostra il contesto completo (utente, azienda, richiesta, dati), lo stack dell'eccezione se presente, un suggerimento per risolvere il problema quando disponibile e il documento collegato con un link per aprirlo (ad esempio la fattura scartata).
Ritrovare l'errore segnalato da un utente
Ogni richiesta e ogni operazione hanno un trace_id. Quando un utente vede un errore, il messaggio riporta un
Codice errore: è il trace_id.
- Fatti dare il codice errore dall'utente.
- Incollalo nel filtro Traccia (con sezione Tutte e un periodo adeguato).
- Trovi tutti gli eventi di quella richiesta, in tutte le sezioni.
Lo stesso codice compare negli errori restituiti dalle API (vedi API).
Esportare
Esporta CSV scarica gli eventi che corrispondono ai filtri attivi.
Regole di avviso
Con Regole di avviso l'amministratore definisce quando essere avvisato, per sezione e livello, con una soglia nel tempo. Esempi:
| Regola | Azione |
|---|---|
| almeno 1 errore nella sezione SDI / e-invoicing | notifica in app agli amministratori |
| più di 20 avvisi in un'ora nella sezione Autenticazione | e-mail agli amministratori |
Le notifiche arrivano nel pannello notifiche degli account di istanza; le e-mail usano la configurazione SMTP (vedi Impostazioni).
Retention
Gli eventi nel database vengono conservati per un periodo che dipende dal livello, poi eliminati e compattati dal job di pulizia:
| Livello | Conservazione predefinita |
|---|---|
| Errori | 365 giorni |
| Avvisi | 180 giorni |
| Informazioni | 90 giorni |
| Debug | 7 giorni |
I periodi si cambiano in Impostazioni → Retention. L'output standard del container segue invece la gestione dei log di Docker.
Log e audit: la differenza
Il log serve alla diagnosi e ha una retention. Due registri distinti servono invece a ricostruire chi ha fatto cosa:
- Storico del record (
audit_logdell'azienda): ogni inserimento, modifica o eliminazione su anagrafiche, documenti, registrazioni e impostazioni, con le differenze; si apre dal pulsante Storico del record. - Audit di sicurezza (
sys_security_audit, nel database di sistema, immutabile): accessi, permessi, licenze, backup, ripristini, operazioni sui database, manutenzione.
Permessi
La pagina è riservata agli account di istanza. Il super utente vede ogni log. Lo strumento MCP get_log_errors
(vedi MCP) espone gli errori recenti solo alle chiavi di amministratori.
Domande frequenti
- Il log contiene password o segreti? No: i segreti non vanno mai scritti nel log né nella diagnostica.
- Dove vedo gli errori dell'interfaccia? Nella sezione UI / circuiti, con lo stack completo.
- Una pagina è lenta. Guarda la sezione Prestazioni: le query oltre 500 ms e le richieste lente sono registrate lì.
Pagine correlate
Stato sistema · Attività programmate · Impostazioni · Utenti e permessi · API · MCP