A customer setting changes overnight, and the support team wants to know why. The database contains the new value. An application log contains several unrelated requests. Neither explains which authorized action changed the setting or whether the action came from an employee, an integration or a scheduled process.
SaaS audit log design is about preserving an understandable account of material changes. It differs from collecting every diagnostic message. An investigation needs the business action and its context, while a debug log may primarily explain how one component behaved.
Begin with the questions an investigation asks
Take a fictional wholesale portal where staff can change a customer's purchasing limit. A useful audit event identifies the actor, the customer workspace, the affected record, the action, its time and its outcome. Depending on the field, it may also record the previous and new values or a safer structured description of the change.
Decide which events matter before instrumenting everything. Membership changes, access changes, exported data and consequential business settings may deserve attention. A routine screen refresh usually answers a different operational question. Naming events around business actions helps people understand them without reading application source code.
Include system actors explicitly. A scheduled adjustment should have a recognizable system identity and a link to its initiating job or rule. Writing administrator as the actor for every internal action destroys distinctions that become important during a support conversation.
Connect the event with the successful change
Consider the failure between updating a purchasing limit and writing the event that explains it. If the update succeeds but the audit write fails silently, the history becomes incomplete. Choose a persistence design that handles this failure deliberately, such as an appropriate transaction or a durable event-delivery pattern.
Also distinguish an attempted action from a completed one. A rejected permission change can be useful evidence, but it should not appear as though the membership was successfully updated. Outcome and correlation fields help separate the request, its result and any later correction.
This work belongs in the custom application's data design, because adding a visual history tab afterward cannot reconstruct facts that were never recorded.
Store evidence without collecting every secret
OWASP's logging guidance discusses useful event attributes, exclusion of sensitive information and protection of log data. Apply that discipline to audit records. Credentials, session tokens and sensitive free-text fields should not be copied into a change event merely because they were present in the request.
For the wholesale portal, a structured event could identify that a restricted note changed without duplicating the note's full content into a widely searchable log. Decide what evidence the investigation genuinely needs, which users may see it and how long it should be retained under the organization's requirements.
Avoid claiming that append-only application permissions make data impossible to tamper with. They restrict ordinary modification, but privileged access, backups and infrastructure controls still matter. Describe the assurance your implementation actually provides.
Make the history useful to a human
Let authorized reviewers filter by workspace, actor, target and time. Show times consistently and distinguish a person's current display name from their stable identity. Keep a traceable record identifier so an investigation can refer to one event unambiguously.
Test a permitted change, a denied attempt, a background change and a failure in event delivery. Ask support to reconstruct the fictional purchasing-limit incident from the resulting history. If they can explain what happened without unrestricted database access or guesswork, the audit trail is doing its job.



