The instance now starts on its own from KHAEMHAT_* variables: it migrates the system and company databases, creates the super user and the first company, and only then reports ready. Users sign in with password and TOTP through revocable database sessions, and licences decide which modules and how many companies are available. - Configuration: every wrong variable reported at once (exit code 2), _FILE variants - Accounts, password policy and lockout, TOTP with recovery codes, session states with token rotation, security audit with a hash chain - Sign-in pages (mockups 001-003), authorization attributes, security headers and a CSP without inline scripts, login rate limit - Signed licences, activation codes, test mode, licence tool - DataProtection keys in the system database, encrypted with the instance key - Memory or Redis cache (in-house RESP client) that falls back to memory - Database log by section with trace id; cron scheduler with locks and system jobs; record history (audit_log) - Company creation, states, company context and X-Company, 503 in maintenance - In-memory SQLite databases stay alive for the process (tests, demo) - Tests for all of the above, ADR 0019, wiki, SECURITY, CHANGELOG, STATUS, DATA-MODEL Refs #15 #16 #17 #18 #19 #20 #21 #22 #23 #24 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
7.2 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 | creazione, emissione, annullamento di documenti |
| 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 |
| 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