Audit logs should answer human questions

A log can be complete and still be hostile.

Timestamps, event names, IDs, and raw JSON are useful only if the reader already knows the schema and the system’s permission model. The audit log should answer the questions people ask when something is already wrong:

• what happened?
• who initiated it?
• who executed it?
• what changed?
• was it allowed?
• can it be undone?

Use nouns a support or security person can scan:

workspace.member_removed
api_key.created
policy.exception_granted
file.permission_revoked
agent.tool_approved

For state changes, preserve the field that moved and its before and after values. Redact sensitive data deliberately, but do not replace the explanation with an empty object.

{
  "event": "workspace.retention_policy_changed",
  "actor": "admin@example.com",
  "field": "logRetentionDays",
  "before": 365,
  "after": 30,
  "source": "admin-console",
  "requestId": "req_789"
}

The actor may need more than one name. A human can initiate an action that a service account executes under a delegated grant. An agent can use a credential that expires at the end of a run. Keep initiator, executor, and authority separate when that distinction matters.

Denials deserve the same care as successes. A denied access attempt may reveal probing, explain a customer failure, or show that a policy rollout was too broad. Record the attempted action, target, reason, blocking policy, and source.

The event shape should support the searches people actually run:

show me everything this user changed yesterday
show me who touched this resource
show me failed API-key creation attempts
show me actions made through impersonation
show me events tied to incident INC-1842

For automation-heavy systems, connect the chain: retrieve data, propose action, approve, execute tool, verify result, notify user. Run IDs, request IDs, and incident IDs are not administrative decoration. They are how a person moves through the timeline without joining six systems by hand.

The test I keep coming back to is simple: can a tired person explain what happened without becoming a detective?