In short
An audit log should record attributable, chronological product events with the actor, action, target, time, context, and outcome. Use structured event types, preserve meaningful before-and-after values, protect logs from alteration, and design a human-readable view for investigation rather than exposing raw application logs.
Decide what the log is for
Security logs, debugging logs, analytics events, and audit trails overlap, but they are not the same product.
An audit trail exists to reconstruct consequential actions: permissions changed, data exported, a payment refunded, a record approved, an integration connected, or an account deleted. Its audience may include account owners, support, security teams, auditors, and customers investigating their own organisation.
Write the questions the log must answer before deciding what to record. Who changed this role? Which records were included in the export? Was the action successful? Did it come from a person, an API key, an automation, or support acting on behalf of a customer?
Use structured events
Store events as structured data, not handcrafted sentences.
Each event should normally include:
- A stable event ID.
- A precise timestamp and time-zone basis.
- The actor and actor type.
- The action performed.
- The target resource and stable identifier.
- The organisation or workspace scope.
- The outcome: succeeded, failed, or partially completed.
- Relevant context such as request, session, or source integration.
The interface can turn that structure into "Mira changed Jonas from Editor to Viewer." The underlying event remains queryable by actor, action, resource, date, and outcome.
Avoid using prose as the source of truth. Copy changes should not make historical events impossible to search consistently.
Record changes, not only activity
"Settings updated" is technically an event and practically useless.
For consequential fields, record what changed from and to. A permission event should name the previous and new role. A configuration event should identify the changed setting. A bulk action should link to a manifest or summary that shows its scope.
Be selective. Capturing the complete before-and-after object may collect secrets, personal data, access tokens, or content the audit viewer should not see. Define an allowlist of auditable fields and redact sensitive values before they reach the log.
Preserve attribution through the system
Background jobs often perform the final database write, but "worker-7" is not the meaningful actor. Carry the initiating identity through queues and services so the audit event can distinguish the executor from the originator.
The same applies to impersonation and support access. Record both the staff member and the customer context they acted within. For API activity, identify the credential or integration as well as its owning account.
Attribution should survive retries. If a job runs twice, event IDs and request correlation should help determine whether the product performed one action or two.
Make the trail resistant to alteration
People who can change production data should not silently rewrite the evidence of that change.
Restrict write and delete access to audit storage, define retention rules, monitor gaps, and consider append-only or tamper-evident storage where risk warrants it. Clock consistency matters too: events from several systems are difficult to reconstruct when timestamps disagree or omit their time zone.
An audit log should also record failures when they are relevant. Repeated denied exports or failed permission changes may matter as much as successful actions.
Design the investigation experience
A raw chronological stream becomes unusable quickly. Give people filters for date, actor, action, resource type, and outcome. Let them open an event for context without making the main list unreadable.
Use product language in the interface. "Changed billing role" is better than membership.permission_set.updated. Keep the stable internal event type available for support and exports.
Link actors and resources when the viewer still has permission to see them. When a user or resource has been deleted, preserve a safe historical label and identifier so the event does not collapse into "Unknown changed Unknown."
Test reconstruction
The best audit-log test is a reconstruction exercise. Give someone a realistic incident and ask them to establish the sequence using only the log.
Can they tell who initiated the action, which records were affected, whether it completed, and what changed? Can they distinguish a user action from an automation? Can they follow events across services? If the answer requires database access or developer guesswork, the trail is not yet doing its job.
Primary references
Common questions
Is an activity feed the same as an audit log?
No. An activity feed helps collaboration and may omit technical or sensitive events. An audit log prioritises attributable reconstruction, controlled access, retention, and integrity.
Should customers see the audit log?
Often, especially in collaborative or regulated products. Build a permission model for it and redact internal or sensitive details rather than exposing the raw operational log.
How long should audit events be retained?
Retention depends on product risk, customer contracts, regulation, investigation needs, and privacy obligations. Define it explicitly rather than keeping everything forever or deleting evidence with ordinary records.
