Mirrored from /mnt/DATA/git/govoplan-audit/docs/AUDIT_TRACE_CONTEXT.md.
Origin: repository.
Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
Audit Trace Context
Operational audit entries should let an administrator answer four questions:
- who initiated the operation
- what object was changed
- which lifecycle request or run carried the change
- how the entry connects to surrounding request, installer, or worker logs
The actor, tenant, scope, action, object type, and object ID remain first-class
audit_log columns. Additional operational context belongs in details.
Standard Fields
Use these fields for admin, module lifecycle, installer, and worker operations:
module_id: module affected by the operation, when a single module is the
target.request_id: queued installer/admin request identifier.run_id: installer/worker run identifier.outcome: compact state such as planned, queued, applied,
cancelled, failed, or completed._trace.correlation_id: request or workflow correlation ID._trace.causation_id: event, run, or operation that caused this audit entry.
Bulk operations may also include concise arrays such as activated,
deactivated, mounted, planned_modules, or sanitized items.
Redaction
Audit detail payloads must not contain credentials, tokens, raw cookies,
authorization headers, private keys, message bodies, uploaded file content, or
other secret material. Use stable IDs, vault references, or package identifiers
instead.
The compatibility helper in core, audit_operation_context, keeps the standard
fields compact and applies the shared audit redaction pass to additional detail
values. Feature modules should follow the same shape even when they later write
through a dedicated audit sink capability.
Module Lifecycle Events
Module install, uninstall, enable, disable, rollback, and package-catalog
acceptance events should include:
object_type: module_install_plan, module_install_request,
module_state, or another stable lifecycle object type.object_id: module ID for single-module actions, otherwise global or the
request/run ID.details.module_id, details.request_id, or details.run_id when present.details.outcome with the lifecycle result.details._trace when the operation originated from a request or queued
daemon action.
This keeps admin UI timelines, audit exports, and rollback diagnostics aligned
without coupling modules to the audit table implementation.