Files
Khaemhat/docs/wiki/Log.md
T
Alby96andClaude Opus 5.5 4123ccacb2
CI / Build and test (SQLite) (pull_request) Canceled after 0s
CI / PostgreSQL 16 integration (pull_request) Canceled after 0s
CI / PostgreSQL 17 integration (pull_request) Canceled after 0s
CI / Docker image (pull_request) Canceled after 0s
CI / YAML check (pull_request) Canceled after 0s
docs: user guide with real screenshots, developer README and M5 closing (#53 #54)
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>
2026-11-12 17:38:14 +01:00

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

  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