Files
Khaemhat/docs/wiki/Log.md
T
Alby96andClaude Opus 5.5 032c602b49
CI / Build and test (SQLite) (pull_request) Successful in 55s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 5s
CI / Docker image (pull_request) Failing after 2m4s
feat: system and security - start-up, accounts, sign-in, licences, log, jobs, companies (M2)
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>
2026-11-11 15:29:24 +01:00

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 (header X-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

084 · Amministrazione · log avanzato per sezioni con filtri e dettaglio

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:

  1. sull'output standard del container in formato JSON, una riga per evento (visibile con docker logs);
  2. 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

  1. Scegli la sezione a sinistra (oppure Tutte).
  2. 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).
  3. 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.

  1. Fatti dare il codice errore dall'utente.
  2. Incollalo nel filtro Traccia (con sezione Tutte e un periodo adeguato).
  3. 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_log dell'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