auditrum

A timestamp and a diff tell you a value changed. They don’t tell you that it changed because support processed a refund request, in a task that came from a particular HTTP request. auditrum carries that context from the application into the trigger, so it is stored on the event rather than reconstructed from logs afterwards.

A reason can be attached with a decorator or a context manager. In Django, request id and actor come from middleware; management commands can declare their own source, so migrations and shell sessions are attributed rather than anonymous.

from auditrum.context import with_change_reason


@with_change_reason("User requested password reset")
def reset_password(user_id):
    ...


from auditrum.context import audit_context

with audit_context.use_change_reason("Bulk update for compliance"):
    ...

Add the integration to INSTALLED_APPS, add two middlewares, and put the models you want audited in an audit.py next to your admin.py — it is discovered and executed the same way. migrate then creates the audit table and installs the triggers.

What gets tracked is per model: only certain fields, everything except certain fields, or only when a SQL condition holds.

# yourapp/audit.py
from auditrum.integrations.django.audit import register

from .models import Product, Subscription, User

register(User, track_only=["name", "email"])
register(Product, exclude_fields=["created_at", "updated_at"])
register(Subscription, log_conditions="NEW.is_active = TRUE")

Because every event stores the full row, the latest event at or before a timestamp is the state at that timestamp. Two PL/pgSQL helpers do the lookup server-side — for one row, or for every surviving row of a table — so reconstructing last Tuesday’s invoice does not mean shipping the whole history to Python and replaying it.

The same thing from the command line is blame: the history of a single row, or a single column of it, in the shape git taught everyone to read. --format json for when it feeds something else.

# everything that ever happened to this row
auditrum blame users 42

# just one column
auditrum blame users 42 email

# the row as it stood at a past moment
auditrum as-of users 42 --at '2026-01-15T10:00:00Z'

An audit log the application can rewrite is a log that proves nothing in the situation it exists for. Three building blocks address that, and each can be turned on by itself — none of them is on by default, because each has a cost worth choosing deliberately.