Prerequisites

What an Audit Log Is

An audit log is a durable, ordered record of security-relevant actions, capturing the acting identity, the operation performed, the resource affected, the outcome, and the time. It exists to answer questions after the fact, under conditions where memory and assumption are insufficient.

Audit Logs Versus Application Logs

Conflating these two is the most common structural mistake. They serve different readers, carry different guarantees, and have different lifetimes.

What to Record

Volume is not the objective. Recording everything produces noise that obscures the events that matter and inflates cost without improving investigation.

Anatomy of an Audit Event

A well-formed event is self-contained. An investigator reading it years later, without access to the original system, should still understand what occurred.

{
    "eventId": "evt-8f41c290",
    "schemaVersion": 2,
    "occurredAt": "2026-09-24T04:18:42.317Z",
    "recordedAt": "2026-09-24T04:18:42.492Z",
    "eventType": "report.exported",
    "category": "data-access",
    "severity": "high",
    "outcome": "success",
    "actor": {
        "type": "user",
        "id": "user-4821",
        "displayName": "Example User",
        "authMethod": "oidc",
        "authLevel": "mfa",
        "sessionId": "sess-2b91f0",
        "onBehalfOf": null
    },
    "action": {
        "operation": "export",
        "method": "POST",
        "endpoint": "/api/reports/export"
    },
    "resource": {
        "type": "financial-report",
        "id": "report-7734",
        "tenantId": "tenant-1042",
        "classification": "confidential",
        "recordCount": 4820
    },
    "context": {
        "sourceIp": "203.0.113.47",
        "userAgent": "Mozilla/5.0",
        "requestId": "req-cc71e4",
        "traceId": "trace-9a2d5f",
        "region": "ap-south-1",
        "deviceManaged": true
    },
    "decision": {
        "policyId": "POL-0042",
        "effect": "Permit",
        "reason": "tenant-scoped export permitted for finance role"
    }
}

Two Timestamps, Not One

Recording both reveals pipeline delay. A single timestamp makes a backlogged collector look identical to an ordered sequence, which distorts any timeline reconstruction.

Capturing the Real Actor

In distributed systems, the service performing the write is rarely the party that initiated it. Recording only the immediate caller produces an audit trail that names your own services.

{
    "actor": {
        "type": "service",
        "id": "report-service",
        "onBehalfOf": {
            "type": "user",
            "id": "user-4821",
            "sessionId": "sess-2b91f0"
        }
    }
}

Where to Emit Events

Durability and Consistency

An audit event that is lost when the process crashes provides no assurance. The relationship between the business write and the audit write must be deliberate.

BEGIN;

UPDATE financial_reports
SET status = 'archived',
    updated_at = CURRENT_TIMESTAMP
WHERE report_id = :report_id;

INSERT INTO audit_outbox (
    event_id,
    event_type,
    actor_id,
    on_behalf_of_id,
    resource_type,
    resource_id,
    tenant_id,
    outcome,
    payload,
    occurred_at,
    published_at
)
VALUES (
    :event_id,
    'report.archived',
    :actor_id,
    :on_behalf_of_id,
    'financial-report',
    :report_id,
    :tenant_id,
    'success',
    :payload_json,
    CURRENT_TIMESTAMP,
    NULL
);

COMMIT;

The outbox makes the audit record share the fate of the business change. Either both commit or neither does, and a relay process forwards unpublished rows to durable audit storage.

Tamper Evidence

An attacker who gains sufficient access will attempt to remove traces. Audit logs cannot always prevent modification, but they can make modification detectable.

function buildChainedEntry(event, previousHash) {
    const canonical = canonicalizeJson({
        eventId: event.eventId,
        occurredAt: event.occurredAt,
        eventType: event.eventType,
        actor: event.actor,
        action: event.action,
        resource: event.resource,
        outcome: event.outcome
    });

    const entryHash = sha256Hex(previousHash + canonical);

    return {
        sequence: event.sequence,
        payload: canonical,
        previousHash: previousHash,
        entryHash: entryHash
    };
}

function verifyChain(entries, genesisHash) {
    let expectedPrevious = genesisHash;

    for (const entry of entries) {
        if (entry.previousHash !== expectedPrevious) {
            return {
                valid: false,
                brokenAt: entry.sequence,
                reason: "previous hash mismatch"
            };
        }

        const recomputed = sha256Hex(
            entry.previousHash + entry.payload
        );

        if (recomputed !== entry.entryHash) {
            return {
                valid: false,
                brokenAt: entry.sequence,
                reason: "entry hash mismatch"
            };
        }

        expectedPrevious = entry.entryHash;
    }

    return { valid: true, verifiedCount: entries.length };
}

Audit Logs as a Data Exposure

Audit logs concentrate sensitive information and are often retained far longer than the data they describe. They routinely become the least protected copy of regulated data.

{
    "eventType": "customer.updated",
    "resource": {
        "type": "customer",
        "id": "customer-9021"
    },
    "changes": [
        { "field": "email", "changed": true, "previousHash": "a3f9...", "newHash": "7c2b..." },
        { "field": "phone", "changed": true },
        { "field": "displayName", "changed": false }
    ]
}

Recording that a field changed, without recording its value, preserves accountability while avoiding a long-lived copy of the data in a system with different access controls.

Storage and Query Design

Audit volume grows steadily and is queried rarely but urgently. The access pattern is narrow and predictable: a specific actor, resource, or time range during an investigation.

CREATE TABLE audit_events (
    sequence        BIGINT       PRIMARY KEY,
    event_id        VARCHAR(64)  NOT NULL UNIQUE,
    occurred_at     TIMESTAMP    NOT NULL,
    recorded_at     TIMESTAMP    NOT NULL,
    event_type      VARCHAR(80)  NOT NULL,
    category        VARCHAR(40)  NOT NULL,
    outcome         VARCHAR(20)  NOT NULL,
    actor_type      VARCHAR(20)  NOT NULL,
    actor_id        VARCHAR(80)  NOT NULL,
    on_behalf_of_id VARCHAR(80)  NULL,
    resource_type   VARCHAR(80)  NULL,
    resource_id     VARCHAR(80)  NULL,
    tenant_id       VARCHAR(80)  NULL,
    source_ip       VARCHAR(45)  NULL,
    trace_id        VARCHAR(64)  NULL,
    payload         JSONB        NOT NULL,
    previous_hash   VARCHAR(64)  NOT NULL,
    entry_hash      VARCHAR(64)  NOT NULL
);

CREATE INDEX idx_audit_actor_time
    ON audit_events (actor_id, occurred_at DESC);

CREATE INDEX idx_audit_resource_time
    ON audit_events (resource_type, resource_id, occurred_at DESC);

CREATE INDEX idx_audit_tenant_time
    ON audit_events (tenant_id, occurred_at DESC);

SELECT occurred_at,
       event_type,
       actor_id,
       on_behalf_of_id,
       resource_id,
       outcome,
       source_ip
FROM audit_events
WHERE actor_id = :actor_id
  AND occurred_at BETWEEN :window_start AND :window_end
  AND category IN ('data-access', 'administrative')
ORDER BY occurred_at;

Retention

Retention sits between two opposing pressures. Keeping logs too briefly destroys evidence before slow-moving compromises are discovered. Keeping them indefinitely accumulates liability and cost.

From Recording to Detection

Logs that are only read after an incident provide forensics without prevention. The same stream can drive detection when specific patterns are monitored.

Threats and Mitigations

Monitoring the Audit System

Common Design Mistakes

System Design Interview Discussion

Implementation Checklist

Knowledge Check

Summary

Audit logs record who performed which action on which resource, when, and with what outcome. They are distinct from application logs in reader, guarantees, retention, and access control, and conflating the two destroys evidence at the moment it is needed.

A complete event is self-contained, carrying actor, action, resource, outcome, context, decision reason, and both occurrence and recording timestamps. In distributed systems, the originating identity must be propagated so the trail names the real actor rather than an internal service.

Reliability comes from emitting at the authorization boundary and using the transactional outbox pattern so audit records share the fate of the business change. Tamper evidence comes from append-only storage in a separate trust domain, hash chaining, and periodic anchoring.

Because audit logs concentrate sensitive data and outlive the records they describe, they must store identifiers and change indicators rather than values, restrict and audit their own access, and follow a deliberate retention policy.