Audit log format

HISAB keeps several local, append-only logs under %APPDATA%\HISAB\ — a general application log, a privacy-preserving ERP audit trail, and a record of Python sandbox runs. They are plain text and JSONL files on your own machine; nothing is sent anywhere by default.

Where the logs live

Everything is written to your roaming app-data folder. There is no database — these are flat files you can open in any text editor.

• %APPDATA%\HISAB\logs\hisab-YYYYMMDD.log — the general application log (Serilog).
• %APPDATA%\HISAB\Telemetry\erp-audit-YYYYMMDD.log — the ERP read audit trail.
• %APPDATA%\HISAB\AnalysisLog\YYYY-MM-DD.jsonl — one record per Python sandbox run.
• %APPDATA%\HISAB\Telemetry\YYYY-MM-DD.jsonl — agent telemetry (timing + outcome events). Off by default; only written if you opt in under Settings.

Application log

One file per day, rolled at midnight. Each line follows this template:

2026-06-10 14:32:07.881 [INF] HISAB Addin logger initialized — v2.0.0, level=Information

Fields are: timestamp (local, millisecond precision), a three-letter level (DBG, INF, WRN, ERR), and the message. The default minimum level is Information. Exception text is run through a redactor before it hits disk, so machine-local file paths, SQL fragments, and connection-string pieces are stripped out.

ERP audit log

Every read against a connected ERP or database source is recorded — one pipe-delimited line per operation. Query bodies are never stored: they are reduced to a SHA-256 fingerprint so the log proves which shape of activity happened without duplicating your financial data on disk.

2026-06-10T14:32:07.881Z | conn-xero-01 | list_invoices | fp:9f3a1c4b2e07d5a8 | 214ms | ok | ai_authoring | chain:1a2b3c4d5e6f7a8b

The fields, in order:

• ISO-8601 UTC timestamp (millisecond precision, Z suffix).
• Connection id — the identifier of the source that was queried.
• Operation — the adapter call name (e.g. list_invoices).
• fp: — first 16 hex chars of the SHA-256 of the query/filter. - when there was no query body.
• Duration in milliseconds.
• Status — ok, error, or blocked (the read-only guard rejected the call).
• Source — ai_authoring, automation_run, or user_direct.
• An optional final field with a short error note.
• chain: — an 8-byte HMAC tag chaining each line to the previous one (tamper-evidence; see below).

Viewing and clearing it

Open the Settings panel, go to the ERP section, and use "View today's log" to tail the most recent entries inline, or "Clear log" to delete today's file (or every file). The log is append-only and HISAB never deletes ERP entries automatically within the retention window.

Python sandbox log

Each script the AI runs in the Python sandbox is recorded as one JSON line. By default only metadata is kept — the code itself is hashed, not stored, and stdout/stderr/results are omitted, because those can contain workbook cell values and ERP rows.

{"ts":"2026-06-10T14:32:07.881Z","session":"...","purpose":"...",
 "code_sha256":"...","code_bytes":412,"success":true,
 "error_type":null,"duration_ms":340,
 "host_calls":["read_rich_range","bulk_write"],
 "code":"[redacted; set PythonLogScriptVerbose=1 to capture]","verbose":false}

Setting PythonLogScriptVerbose=1 opts in to capturing the full code, stdout, stderr, traceback, and result (and a human-readable .py/.out pair per run). Leave it off unless you are debugging.

Retention

A housekeeping sweep runs at Excel startup and prunes these folders by file age (and, for logs, by total size). Retention is the same for every plan and is overridable via app.config keys, not by license tier:

• logs\ — 30 days, plus a 50 MB per-file and 500 MB total cap.
• Telemetry\ (agent telemetry JSONL) — 30 days.
• AnalysisLog\ — 7 days (shorter, because it can contain sensitive workbook data).

The ERP audit log (erp-audit-*.log) lives in the Telemetry folder and follows that 30-day sweep; you can also archive or clear it manually at any time from the ERP Settings panel.