Audit Logging

A different kind of log

An audit log is a record of security- and accountability-relevant actions: who performed an action, what they did, when, and often from where. It is not the same as the operational logs you use to debug. Debug logs are verbose, noisy, and short-lived; audit logs are selective, durable, and treated as evidence.

Because they serve different purposes, keep them separate. Mixing high-volume debug output with audit records makes the audit trail hard to read and hard to protect. An auditor or incident responder wants a clean account of significant actions, not a firehose of routine application chatter.

What deserves an entry

Audit the events that matter for security and accountability: authentication (logins, failures, token issuance), authorisation changes (granting or revoking access), and access to or modification of sensitive data. Administrative actions and configuration changes belong here too, because they shape what everyone else can do.

Not every action needs auditing — recording every read of a public resource would bury the signal. Focus on actions that change state, touch sensitive data, or alter who can do what. These are the events someone will one day need to reconstruct after an incident or a dispute.

Capture enough to reconstruct

An audit entry must answer the investigator's questions on its own. Record the actor (who), the action and its target (what), the time (when), the source (from where, such as an address), and the outcome (succeeded or failed). A correlation identifier ties the entry to the surrounding request flow.

{
  'ts': '2026-06-29T04:20:00Z',
  'actor': 'user:4821',
  'action': 'record.export',
  'target': 'case:9930',
  'source_ip': '203.0.113.7',
  'result': 'allowed'
}

Record the fact of the action, not the sensitive payload itself. The aim is an entry that a reviewer who was not present can read in isolation and still understand: who acted, on what, when, from where, and whether it succeeded. Fields that seem redundant in the moment — the source address, the precise timestamp, the outcome of a denied attempt — are exactly the ones an investigation later depends on, so capture them consistently rather than only when something has obviously gone wrong.

Protect the record

An audit log is only trustworthy if it cannot be quietly altered. Make entries append-only and restrict who can read or modify them, so the record of an action cannot be edited away by whoever performed it. Where stronger guarantees are needed, techniques such as write-once storage help demonstrate the log has not been tampered with.

Guard against the log itself becoming a liability: audit entries should reference sensitive data, not reproduce it, so the trail does not turn into a second copy of the very information you are protecting. Apply a retention period that meets your obligations without keeping detailed records indefinitely.