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.

Access Provenance

Access-sensitive events should include a compact provenance array when the decision depends on semantic access state. Use details.access_provenance with items shaped like AccessDecisionProvenance.to_dict() from govoplan_core.core.access.

Expected provenance kinds:

identity
account
tenant_membership
organization_unit
function
group
role
right
delegation
policy
system_actor

Delegation and acting-in-place events must show both the real actor account and the represented/delegated account or function assignment. Feature modules should obtain this shape through access.explanation instead of inspecting access tables directly.

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.

Commands, Events, And Outbox Delivery

Commands and events are separate concepts:

Commands are imperative requests to do work, for example retention.run or module.install. They use govoplan_audit.backend.commands.AuditCommand and CommandBus.
Events are completed facts, for example tenant.created or retention_policy.run. They use the core PlatformEvent envelope and may be written to the audit outbox before delivery.

govoplan_audit.backend.outbox.SqlAuditOutbox persists platform events in audit_outbox_events. Dispatchers can later call dispatch_pending_platform_events() to publish pending events and record retry state. The outbox payload stores the full governed event envelope: correlation/causation ids, actor, tenant, subject, resource, classification, module id, event id, type, and payload.

Application code should enqueue or publish facts only after the state change they describe is known. Long-running operators and installers should model requested work as commands first, then emit facts as events as each step completes.

4.1 KiB Raw Blame History