grith audit

grith audit
grith audit diagnose
grith audit export [--format json|csv] [--offset <N>] [--limit <N>]
grith audit compact [--yes]
grith audit rebuild-analytics [--yes]

The audit log is the durable record of every filter decision. Bare grith audit verifies the chain, then prints the last 10 records.

$ grith audit
Audit log: 0 total entries
No audit entries yet.

diagnose

Read-only, no flags, and the one audit command that still works when the chain is quarantined. Run it first whenever anything else refuses.

$ grith audit diagnose
Chain status: writable

Full verification: chain is empty.

Segments: 1 (continuous history)

Duplicate sequences: none.
Sequence gaps: none.

Assessment: no integrity problems detected.

export

Defaults are --format json, --offset 0, --limit 1000. Records come newest first.

$ grith audit export --format csv --limit 2
Showing 0 records (offset 0, limit 2, total 0)
timestamp,plugin_id,tool_call_type,decision,score

The count banner goes to stderr and the data to stdout, so grith audit export > out.json gives you a clean file. Only json and csv are handled; anything else prints Unknown export format: <x>. Use 'json' or 'csv'. and writes nothing.

compact

A manual maintenance operation - never automatic. It rewrites the database to reclaim free pages left by retention pruning, then atomically swaps the file in.

$ grith audit compact --yes
Compaction complete.
On-disk: 200704 -> 200704 bytes (0 reclaimed)
Free pages inside DB: 0 -> 0 bytes (0 reclaimed)

Without --yes it asks first, and a closed stdin counts as no:

$ grith audit compact
Compact the audit database (rewrites + atomically swaps the file)? [y/N] Aborted.

rebuild-analytics since 0.3.1

Rebuilds the derived analytics projection from the audit database plus the cold archives under <audit_dir>/cold/. Audit records themselves are never touched - the projection is a view over them, and this recomputes the view.

$ grith audit rebuild-analytics --yes
Analytics rebuild complete: 0 source records processed.

Reach for it when the local dashboard's numbers look wrong, or after restoring an audit database from a backup.

Both maintenance commands refuse in two cases

compact and rebuild-analytics each need exclusive write access to the database, and each bails rather than working on a chain it does not trust:

• A daemon owns the database. The message tells you to stop it first with grith daemon stop. Run the command, then start it again.
• The chain is quarantined. It points you at grith audit diagnose.

See also

• Logging and audit retention - what is pruned, and when
• grith log - the same data, formatted to read