Audit log¶
The optional Orchestra Audit Trail submodule (orchestra_audit_trail)
records every process transition into the
Audit Trail chain: a durable,
tamper-evident log that survives instance deletion. It complements the live
process trace; the trace shows the current run, the audit log is
the permanent record of who did what, and when.
How it works¶
The engine and the inbox dispatch a neutral OrchestraAuditableEvent at each
meaningful transition, with no knowledge of any backend. This submodule
subscribes to that event and writes each one into the Audit Trail chain. The
engine itself keeps zero dependency on audit_trail: enable the submodule
to turn the events into chain rows, or leave it off and consume the events
another way (an ECA model, a custom subscriber).
Enabling the submodule provisions a dedicated orchestra chain in
audit_trail (flag mode) that claims the orchestra channels. Flag mode keeps the
chain to the structured lifecycle events this module records, leaving out plain
engine log lines that happen to share the orchestra channel. Recording then
needs audit_trail to have a signing secret configured (see audit_trail's own
setup). A write that fails (for example before a secret exists) is logged on
the Orchestra channel and never breaks the running workflow, since the audit
log is an optional add-on.
Every row carries the instance UUID as its correlation id, so the audit trail groups all the rows of one process run together.
What it records¶
| Channel | Actions |
|---|---|
orchestra.instance |
started, completed, cancelled, failed, incident_raised |
orchestra.task |
assigned, claimed, completed, reassigned, released, reoffered, cancelled |
orchestra.token |
parked, resumed, cancelled |
orchestra.variable |
set |
Every event can be toggled on the settings form. token park/resume are on by
default; variable set is off by default, as variable writes are high-volume.
A variable event records the variable name and scope (instance-wide or local to
one token branch), never its value, which can be arbitrary or personal data.
Permanent and transient context¶
Audit Trail keeps two context buckets per row: a permanent, HMAC-signed bucket, and a transient bucket that a retention policy can purge. The bridge routes the structured, non-PII fields (workflow, node, tenant, outcome, reason, instance) to the permanent bucket, and leaves the actor and assignee user IDs in the transient bucket, so they stay GDPR-purgeable.
Configuration¶
At Configuration > Workflow > Orchestra > Audit trail, toggle which
(channel, action) pairs are recorded. Everything is on by default. The setting
is read at dispatch time, so a missing entry counts as enabled and only an
explicit off drops that event; that lets you silence a noisy transition without
touching code.
Trace versus audit log¶
The trace and the audit log answer different questions. The trace is live observability: the token trail of a run, rebuilt from its retained tokens, and gone when the instance is deleted. The audit log is the durable record: an append-only, tamper-evident chain that outlives the instance, for compliance and forensics.
Requirements¶
orchestraaudit_trail