beginnerintermediateadvanced

Django · Auditing

Auditing

Three kinds of record, four kinds of event, and one table that must be append-only

Three records, three audiencesapp logs (days) · audit logs (years, append-only) · domain events (the product)
update() emits no signalsso signal-based auditing misses exactly the bulk changes that matter most
Store the diff, not a snapshotthe audit table has your longest retention — redact sensitive fields
Same transaction as the changea change with no audit row is the gap the trail exists to prevent
Audit the failed logins tooa successful login is only evidence next to the forty that failed

1.Timestamps and actors — the cheapest auditing there is

Before any audit system, add four fields: `created_at`, `updated_at`, `created_by`, `updated_by`. They cost almost nothing and answer a surprising share of real questions — when did this appear, when did it last change, and who touched it. What they cannot answer is *history*: `updated_by` holds only the most recent actor, so the previous five edits are gone. That is the gap a state-change history table fills, and knowing exactly where these four fields stop is what tells you when you need one.

Key features

`auto_now_add=True` sets the field once on creation; `auto_now=True` updates it on every `save()`
Both are applied in `save()`, so `QuerySet.update()` silently leaves them stale
When you use `update()` on purpose, set `updated_at=timezone.now()` in the same call
A model cannot see the request — pass the actor in, or read a middleware-set `ContextVar`
`created_by`/`updated_by` must be nullable: commands, tasks and migrations have no user
`updated_by` holds one actor; any question spanning two changes needs a history table

What each tier can answer — and where it stops

What each tier can answer — and where it stops
Question	Timestamps	+ actors	+ history
when was this created?	yes	yes	yes
when did it last change?	yes	yes	yes
who created it?	no	yes	yes
who made the last change?	no	yes	yes
who changed the price to £49?	no	only if nobody touched it since	yes
how long was it in `processing`?	no	no	yes
what did it look like in March?	no	no	yes

Which write paths keep the fields honest

Which write paths keep the fields honest
Write path	`auto_now` fires?	Signals fire?
`obj.save()`	yes	yes
`obj.save(update_fields=[…])`	yes — include the field	yes
`Model.objects.create(...)`	yes	yes
`QuerySet.update(...)`	no	no
`bulk_create()` / `bulk_update()`	no — `save()` is skipped	no
a raw SQL `UPDATE`	no	no

Three tiers — climb only as far as your questions require

Nothing

you cannot even say when the row appeared

created_at / updated_at

two fields, near-zero cost — but stale after any update()

+ created_by / updated_by

the last actor only; nullable, because commands and tasks have no user

+ a state-change history row

from, to, actor, when — the first tier that survives a second edit

+ an append-only audit log

a different audience and a different retention — see the next concept

Command

python

created_at = models.DateTimeField(auto_now_add=True)   # set on save(), not on update()

Four fields answer a lot for almost nothing — but know exactly where they stop. `auto_now`/`auto_now_add` fire in `save()`, so `QuerySet.update()`, `bulk_create` and raw SQL all leave them stale; set them by hand on those paths, or rows will claim they were last changed before the change that just happened. Actor fields must be nullable, because commands, tasks and migrations have no user, and should be passed explicitly rather than read from a global — a module-level current user misattributes rows under concurrency. And `updated_by` holds one actor: any question spanning two edits needs a history row per change.

2.Three kinds of record, and why they are not interchangeable

The roadmap names three things that people call "logging" and treats them as distinct, because they are. **Application logs** are for engineers debugging behaviour — high volume, short retention, disposable. **Audit logs** answer "who did what, to what, when" for someone who is not an engineer — compliance, a customer dispute, a security review — so they are append-only and kept for years. **Business event history** is the record of what happened to a domain object: the states an order moved through. Mixing them gives you one store that serves none of the three well.

Key features

Application log: engineers, this week, high volume, disposable — retention in days
Audit log: non-engineers, years later, append-only — "who did what to what, when"
Business event history: part of the domain, queried by the product itself
`auto_now`/`auto_now_add` are applied on `save()`, so `QuerySet.update()` leaves them stale
`update()` "doesn't run any `save()` methods, or emit the `pre_save` or `post_save` signals"
Store the diff, not a full copy — a snapshot duplicates data and extends its retention

The three, side by side

The three, side by side
Property	Application log	Audit log	Business event history
read by	engineers, debugging	compliance, support, security	the product, and users
answers	"why did this break?"	"who did this, and when?"	"what happened to this order?"
lives in	a log pipeline	a database table	a database table
retention	days to weeks	years, by policy	the object's lifetime
mutable?	irrelevant — it is discarded	append-only	append-only in practice
may lose entries?	yes, acceptable	no — a gap looks like a cover-up	no
contains	anything useful	actor, action, target, time, source	domain states and transitions

What to record, from cheapest to most complete

What to record, from cheapest to most complete
Level	Gives you	Cost
`created_at` / `updated_at`	when, roughly	two fields — and stale after `update()`
`created_by` / `updated_by`	the last actor only	two more fields; history still lost
an append-only audit table	every action, forever	a write per action, and a retention policy
a domain event table	the object's own timeline	modelling work; but the product wants it anyway
full before/after snapshots	everything	duplicated data, and personal data kept for years

One refund, recorded three ways — and what each one can answer

An application log line

Written for whoever is debugging this week
Retention measured in days
May be dropped under load, and that is acceptable
Answers: "why did the refund call fail?"
Cannot answer: "who authorised this in March?"

An audit row and a domain event

Written for compliance, support and security
Retention measured in years, by policy
Append-only, in the database, inside the transaction
Answers: "who authorised this, from where, when?"
And the event answers: "what happened to this order?"

Command

python

updated_at = models.DateTimeField(auto_now=True)   # set on save(), NOT on update()

Three records, three audiences. Application logs are for engineers this week and may be dropped; audit logs are for non-engineers years later and must be append-only and complete; business event history is part of the domain and the product queries it directly. Start with `created_at`/`updated_at` and `created_by`/`updated_by` — but know `auto_now` only fires on `save()`, and `QuerySet.update()` emits no signals, so signal-based auditing has a hole exactly where bulk changes happen. Write the audit row in the same transaction as the change, store the diff rather than a snapshot, and redact sensitive fields — the audit store has your longest retention.

3.What actually needs auditing — and what data access logging costs

Four categories earn an audit row rather than a log line. **Security events**: sign-in, sign-out, failed attempts, password and email changes, permission grants, token issue and revocation. **Administrative actions**: anything staff do to somebody else's data. **Payment events**: every state change to money. **Data access logging**: recording *reads*, not just writes — which is the expensive one, and the only one where "audit everything" is usually the wrong answer.

Key features

Django emits `user_logged_in`, `user_logged_out` and `user_login_failed` signals — audit all three
Failed attempts are the ones that make a successful login meaningful
`django.contrib.admin.models.LogEntry` covers admin additions/changes/deletions — and nothing outside the admin
Staff acting on customer data is its own category: legitimate, and still attributable
Every payment state change gets a row, with the provider reference and the amount
Read logging is the expensive one: reads outnumber writes, so scope it rather than blanket it

The four categories, and the question each one answers

The four categories, and the question each one answers
Category	Record	Answers
Security	login, logout, failed login, password/email change, MFA, token issue+revoke	"was this account compromised?"
Administrative	staff action, target user, impersonation start/end, permission grants	"did staff do something they should not have?"
Payment	every state change, amount, currency, provider reference	"where did this money go?"
Data access	reads of sensitive records; bulk reads especially	"who looked at this?"
(not audited)	page views, ordinary reads, search queries	nothing worth years of storage

Deciding how much read logging to do

Deciding how much read logging to do
Approach	Cost	Right when
none	zero	the data is not sensitive — most systems
sensitive records only	a write per sensitive view	payment details, personal data, customer records
bulk access only	a write per export or wide query	the signal you actually want: one actor, many records
every read	more rows than the data itself	a regulator asks for it — and then it is async

An account compromise, reconstructed from audit rows alone

02:14
41 × auth.login_failed
same username, one IP in a country the account has never used
02:15
auth.login_succeeded
same IP — unremarkable on its own; damning after the line above
02:16
auth.email_changed
the recovery address is moved first, so the real owner cannot reset
02:16
auth.mfa_disabled
the second factor removed while the session is still valid
02:19
data.bulk_access
8,400 customer records read in one query — the read that mattered
02:23
payment.payout_created
new bank details, entered four minutes earlier
09:40
admin.impersonation_started
support investigating — recorded as support, not as the customer

Command

python

@receiver(user_login_failed)   # the signal most systems forget to audit

Audit four categories: security events (including the *failed* logins — a successful one is only meaningful beside them), administrative actions by staff on other people's data, every payment state change, and — deliberately, not by default — access to sensitive data. Django gives you `user_logged_in`, `user_logged_out` and `user_login_failed` for free, and `admin.LogEntry` covers the admin and nothing outside it. Read logging is the expensive category because reads vastly outnumber writes, so scope it to sensitive records and to *bulk* access, which is the signal you actually want.

Spotted a mistake on this page? Tell us.

Read Sheet