Immutable audit trail

Intent

This pattern assumes a platform people administer themselves, through an API that verifies who they are. It makes the audit log immutable by construction: services send events, one writer adds new records, and nothing can update or delete them. This enables three outcomes:

1. Nobody can rewrite history, including the services the trail holds to account.
2. Every entry reads the same, whichever service sent it.
3. A new source can be added without changing the store.

Motivation

Without this pattern, who changed what is left to one of two records, and neither proves much:

1. Log lines. They age out, and they prove nothing about who was allowed to do what.
2. An audit table that services write directly. It can be edited by the same services it's meant to hold to account.

This pattern rests immutability on permissions and a conditional write, which no change to a producer's code can get around. Each producer commits a change and its event together, as in a transactional outbox, so no action succeeds without its record. One contract means every event reads the same, and a queue such as Amazon SQS between producers and the store lets new sources join with nothing more than permission to send.

Applicability

Use this pattern when:

1. People administer a platform themselves, such as creating tenants, changing settings or managing users.
2. You need a record of who did what, and when, such as alongside a multi-tenant API, a multi-tenant portal frontend or config as data, where people change what each client gets.
3. Every actor signs in through an identity provider, as in multi-tenant Cognito auth, so the actor on each entry comes from a verified token and can't be spoofed.
4. Nobody may alter that record afterwards, including the services that made the changes.

Do not use this pattern when:

1. The events are high-volume and operational, such as every read or pipeline step, which belong in logs and metrics. The trail is for actions someone must be accountable for.

Structure

Participants

Constraints and trade-offs

1. Append-only isn't the same as true. A faulty or compromised producer can still add a false entry, so the trail guarantees that history can't be rewritten, not that every entry is accurate.
2. Committing a change and its event together adds a relay to every producer, and an event can then arrive more than once, which the writer treats as success.
3. Events arrive after a hop, so a record appears once the queue and writer have handled it, not the instant the action completes.
4. The trail only grows, because it has no expiry by design, so old entries need archiving to cheaper storage if volume climbs.

Part of how I deliver

When someone has to answer for who changed what, this is the record I give them. It's one of many patterns I bring through contract delivery, and it extends to new sources as your platform grows.

Related