Audit Logging

Audit logging records who did what, when, and from where for security-sensitive actions, supporting investigation and accountability rather than debugging.

security

Definition

An audit log is an append-only record of security-relevant events such as authentication, authorization decisions, data access, and configuration changes, capturing actor, action, target, timestamp, and outcome so activity can be reconstructed later.

Context and scope

Audit logs support incident investigation, regulatory compliance, and insider-threat detection. They differ from application logs in purpose and guarantees, because audit records are about accountability, tamper evidence, and defined retention.

Common misconceptions

Audit logs are ordinary application logs with a different file name
Logging every request produces a complete audit trail
Audit records can share a mutable table with business data

Anti-patterns

Storing audit records where the application can update or delete them
Recording free-text actor names instead of stable user or service identifiers
Capturing tokens, passwords, or full personal data in audit payloads

Related concepts

Related examples

Authoritative source

https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html

How it works

When a protected action occurs, the service emits a structured event and writes it to durable, append-only storage.

{"event_id":"01J9Z6","ts":"2026-10-20T08:15:02Z","actor":"user:4821","action":"role.grant","target":"project:918","outcome":"success","ip":"203.0.113.9"}

Good records carry a stable actor identifier, the action, the target, the outcome, a timestamp from a synchronized clock, and a request or trace ID. The pipeline should add sequence numbers or hash chaining so gaps and edits are detectable. Events leave the application through a dedicated stream or queue, land in write-once storage such as object lock or an append-only ledger, and are indexed for investigation.

When to use it

Emit audit events for sign-in and sign-out, permission and role changes, access to sensitive records, exports, billing changes, key and configuration changes, and administrative impersonation. Compared with application logs, audit logs are lower volume, schema-strict, access-controlled, and retained longer. Compared with distributed tracing, they answer who did this rather than where the request spent time.

Trade-offs

Immutability and long retention cost money and complicate deletion obligations; more context improves investigations but increases the chance of storing personal data. A synchronous write adds latency, so buffer through a durable queue rather than dropping events. Audit storage must also survive compromise of the application account.

Concrete example

An administrator grants a role at 08:15. The audit event records actor user:4821, action role.grant, target project:918, and outcome success. During a later review, an analyst filters by target and reconstructs every permission change on that project, including a rejected attempt ten minutes earlier.

Audit logs are not debugging logs, and log-everything is not an audit trail: noise hides the events that matter and multiplies privacy exposure. Audit records pair with least privilege because they reveal who can change what, and they must respect PII handling and retention schedules that define when they are destroyed.