Table of Contents

Audit Trace Context

Standard Fields
Redaction
Module Lifecycle Events

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.