An audit log should provide reliable evidence of significant activity in a web application. It is not the same as a technical error log, and it should not be treated as a record of every click. The useful starting point is to decide which business, security and administrative events must be explainable after they occur.

Good audit logging supports investigation, accountability and operational control. Poor logging creates large volumes of data without answering basic questions such as who changed a record, what changed, whether the action succeeded and why an override was allowed.

Decide what the audit log is for

Start with the questions the business may need to answer

Examples include:

  • Who approved or rejected this request?
  • Which user changed the customer's bank details?
  • Was access removed when a contractor left?
  • Which records were included in an export?
  • Why did an automated integration alter this status?
  • Who changed a permission, configuration or retention rule?
  • Did a high-impact action fail, and was it retried?

These questions determine what must be recorded. Starting with a generic request to “log everything” usually produces cost, privacy and usability problems without guaranteeing useful evidence.

Distinguish audit logs from other logs

Log type Primary purpose Typical examples
Audit log Explain significant user, administrative or automated actions Approval, role change, export, deletion, configuration change
Application log Help developers and operators understand system behaviour Job started, validation failed, service response received
Security event log Support detection and investigation of suspicious activity Repeated failed sign-in, privilege change, unusual access pattern
Access log Record requests to a service or resource Request time, route, response status and source information

The categories can overlap, but their audiences and retention needs may differ. Do not assume one log stream can serve every purpose equally well.

Design the events and recorded information

Choose the events that matter

Prioritise actions that change rights, money, status, ownership, configuration or sensitive information. Depending on the application, useful events may include:

  • account creation, activation, suspension and deletion;
  • role and permission changes;
  • successful and failed high-risk sign-in events;
  • record creation, approval, rejection, cancellation and reopening;
  • changes to important values;
  • bulk actions and exports;
  • document upload, replacement, approval and deletion;
  • administrative overrides;
  • changes to system, integration or notification settings;
  • automated actions that materially alter a business record;
  • failed actions whose absence could be mistaken for success.

A routine low-impact edit may need only a concise change record. A permission change or financial override may require stronger context and review.

Define the information recorded for each event

Field Purpose
Event type Describes the action in a consistent, searchable way
Actor Identifies the user, service or automated process responsible
Target Identifies the affected record, account, document or setting
Time Records when the event occurred using a consistent time basis
Outcome Shows whether the action succeeded, failed or was partly completed
Change Records the significant before-and-after values where appropriate
Reason Captures a required justification for overrides or exceptional actions
Context Links related actions using a case, request or correlation identifier
Source Distinguishes user interface, API, import, scheduled task or support action

Avoid placing passwords, access tokens, payment credentials or unnecessarily sensitive content in logs. Record enough to identify the event without turning the log into a second uncontrolled copy of the underlying data.

Use stable identities

A display name can change and an email address can be reassigned. The log should retain a stable identifier for the actor while presenting enough human-readable information for investigation.

Automated processes and integrations also need identities. “System changed record” is rarely sufficient. Name the job, service account or integration responsible and link related actions where possible.

Decide how much change detail is necessary

For some events, recording the action and target is enough. For others, the investigator needs to know what changed. Before-and-after values are particularly useful for permissions, statuses, critical settings and important commercial fields.

However, copying an entire record into every event can create excessive storage and expose information that is not needed for the audit purpose. Select the relevant fields and consider whether sensitive values should be masked or represented by a reference.

Set governance and reliability requirements

Plan access to the audit history

Audit data can itself be sensitive. Define:

  • which roles may view it;
  • whether access is limited by team, customer or record;
  • who may search or export it;
  • whether viewing or exporting audit data is also recorded;
  • how support staff obtain temporary access;
  • how inappropriate access is detected and reviewed.

A universal audit-log screen available to every administrator may reveal more information than their role requires.

Protect the reliability of the record

The business should be able to rely on the log when investigating an event. Requirements may include preventing ordinary users from changing entries, separating audit storage from editable business records, controlling privileged access and detecting gaps or failures.

The appropriate design depends on the risk and architecture. Where the log supports security, contractual or regulatory evidence, obtain specialist review rather than assuming that an application table is sufficient.

Define retention and deletion deliberately

Keeping logs indefinitely is not automatically safer. Retention should be linked to a stated operational, legal, security or contractual purpose and reviewed when those needs change.

Document:

  • which log categories exist;
  • how long each category is kept;
  • when it is archived or deleted;
  • who approved the period;
  • how backup copies are handled;
  • how legal or investigation holds are managed where applicable.

Any legal or data-protection conclusion should be checked against the organisation's current circumstances.

Decide what happens when logging fails

An important action can succeed while the audit event fails to record. The business must decide whether that is acceptable.

For low-impact activity, the system may continue and raise an operational alert. For a critical permission change or financial approval, the requirement may be to stop the action if reliable recording is unavailable. Make the decision explicitly and test it.

Make the audit history usable

Design the review experience

A useful audit history should allow an authorised investigator to filter by:

  • date and time;
  • actor;
  • event type;
  • target record;
  • outcome;
  • customer or organisation;
  • related request or process.

Present events in plain language while preserving the underlying identifiers needed for accurate investigation. An unreadable stream of technical messages is not a business audit trail.

Write acceptance scenarios

Test both the action and the resulting evidence. Examples include:

  • When a manager approves a request, the log records the manager, request, decision, time and outcome.
  • When a permission is changed, the old and new access are visible to an authorised reviewer.
  • When an export fails, the log does not imply that data was successfully produced.
  • A user without audit access cannot view the history through the interface, export or direct request.
  • An automated integration is identified by its own service identity rather than a generic system label.
  • A failed audit-write condition produces the agreed application response and operational alert.

Common mistakes

Logging every action without a use case

High volume makes important events difficult to find and increases storage and governance work. Begin with decisions the organisation genuinely needs to explain.

Recording only successful events

Failed approvals, exports and administrative actions may be essential to understanding an incident.

Using mutable names as the only identity

The evidence becomes ambiguous when a user changes email address or display name.

Allowing the same privileged role to act and erase the evidence

Access to configure, perform and alter audit records should be reviewed carefully. Separation appropriate to the risk may be required.

Ignoring operational ownership

A log has little value if nobody is responsible for reviewing alerts, answering investigations or maintaining retention rules.

Questions to ask a supplier

  • Which events will be recorded, and which important events are excluded?
  • How are users, services and automated jobs identified?
  • Which values are recorded before and after a change?
  • How is sensitive information kept out of log entries?
  • Who can view, search and export the audit history?
  • How are entries protected from ordinary alteration?
  • What happens if the application cannot record a critical event?
  • How are retention, archiving and deletion implemented?
  • How will audit behaviour be verified during acceptance testing?

Next step

Select ten high-impact actions in the application and write the question each audit event must answer. For each action, define the actor, target, outcome, change detail, reason and failure behaviour. This creates a useful first audit specification without defaulting to the unmanageable instruction to log everything.