Journal compatibility

The 1.3.3 reader accepts schemas 1 and 2, including mixed archives. Adaptation happens in memory: these formats do not need a migration script.

Supported schemas

schema_version is independent of the software version and api_version. Published 0.0.65 already wrote schema 2 and read both formats. Schema 1 is the earlier historical format.

Reading does not rewrite or repair data files; the companion lock file may be created. Normal writes and rotation still bound retention.

Event values and identity

IDs, correlations, dates and values are preserved. Text uses the journal’s shared visible escapes: control characters and formula prefixes are protected, literal backslashes are doubled, and printable Unicode is preserved. Display the parsed JSON text without interpreting those visible escapes again.

Additional scalar fields are accepted; nested objects and arrays are rejected. Missing fields are not added. These format and text checks do not validate every field’s type or meaning. Handle absent/null values and unknown labels without treating them as success.

Reasons remain English. A started event without a result keeps an unknown outcome: no action is replayed to complete history.

Reads and exports

audit-export reads all retained files oldest first, then applies its filters. HTTP reads bounded pages newest first; its export covers the requested page.

Normalized JSONL preserves additional fields and numeric/null types. It does not replace a byte-for-byte backup of the originals. Re-exporting adds no escaping layer.

CSV uses fixed columns: unknown fields are omitted, numbers become text and absent/null values become empty cells. Use it for analysis, not lossless restoration. There is no CSV import command.

Errors and validation scope

An unknown schema, invalid JSON/text or truncated event stops reading when encountered. The CLI returns 119 before exported data for these read failures, even if a filter would exclude the event. Always check the exit status: other errors, including export output failures, can leave partial output.

HTTP reads return 503 audit_unavailable when a scanned event is invalid, including events excluded by filters. A readable recent page does not certify older unscanned archives. Limits and cursors are described in the HTTP contract.

Appending checks the active file’s final newline without scanning the entire history. Successful writes do not prove archive integrity. On corruption, stop writers and preserve the original files before investigation; a normal export can fail on those files.

Upgrade and rollback

1. Record exact versions, paths and retention settings. Stop all writers, then back up persistent directories, archives, configuration and relevant action state with their permissions.
2. Test the target reader on a copy with the same limits. Check exit status, IDs, event counts and representative text. Never redirect an export to its own input file.
3. Upgrade the agent and matching UI, preserve mounts/settings, then verify collection, the journal and exports.
4. For rollback, stop writes and preserve post-upgrade data separately. Test the older reader on a copy before resuming. Restoring an older backup excludes later events; retain them separately without replaying actions.

For a copy at /srv/monit-audit-check with default limits, use the target version’s CLI:

umask 077
monit-docker --audit-file /srv/monit-audit-check/events.jsonl \
  --audit-max-bytes 5242880 --audit-files 5 \
  audit-export > /srv/monit-audit-check-export.jsonl

Adjust limits to the original configuration. Published 0.0.65 defaulted to 10 MiB per file, compared with 5 MiB since 0.0.66. Lowering this limit does not shrink existing archives and can prevent full reads. Reducing the file count excludes archives outside that range without deleting them.

Future changes

Preserve IDs, field meanings and encoding within a schema. Test additive fields against older readers. Incompatible structure, encoding or meaning changes require an explicit schema decision, supported versions and rollback limits.

Prefer read-time adaptation when it preserves information. If physical conversion becomes necessary, provide an explicit tool before enabling it: dry run, source backup, separate output, identity/count checks and interruption recovery. Since 0.0.78, optional audit-migrate provides simulation and explicit conversion with backups, without replacing the live journal.

Validation and limits

Format tests and upgrade rehearsals from 0.0.78, 0.0.79 and 0.0.82 accompany the 1.0.0 release. They do not certify arbitrary versions or deployments. See the results and limits.