How Do You Design an Audit Log Your Customers Will Actually Use?

How do you design an audit log your customers will actually use?

Design it for one question: who changed this, and when. Everything else follows. Record the actor, the action, the target, the time and the outcome, then build a table people can filter and scan. Most audit logs fail because they were built to satisfy a checklist rather than to answer that question.

Audit logging arrives in a B2B product roadmap the same way for almost everyone. A security questionnaire asks for it, engineering ships a table of rows, and nobody looks at it again until a customer has an incident and discovers it is unusable.

Here is how to build one worth having, and what to record in it.

What should an audit log entry actually contain?

Five fields at minimum: who, what, which thing, when, and what happened as a result. If any of those is missing, the log cannot answer the question people come to it with.

Google Cloud's audit logging documentation is a useful model here because the structure is public. Every audit log is a LogEntry object distinguished by its protoPayload field, which contains an AuditLog object holding the audit data, with log names including resource identifiers and the log type.

The pattern worth copying is that the entry is structured, not a sentence. A log of rendered English strings is impossible to filter reliably. Store the fields separately and render the sentence at display time.

What categories of event are worth logging?

Google Cloud documents four types, and the split is a good starting point for any product. Admin Activity logs record "log entries written by user-driven API calls or other actions that modify the configuration or metadata of resources," such as permission changes. They are always enabled and cannot be disabled.

Data Access logs capture "API calls that read the configuration or metadata of resources" and "user-driven API calls that create, modify, or read user-provided resource data." Google notes these are disabled by default because of their volume, and that enabling them may increase charges. That volume warning is the important lesson for your own product.

System Event logs cover changes made by the platform itself rather than a user, such as autoscaling. Policy Denied logs record when "a Google Cloud service denies access to a user or service account because of a security policy violation." Denied attempts are often the most interesting rows in a real investigation, and most products never log them at all.

Why do most audit log interfaces fail?

Because they present a firehose with no way to narrow it. A customer with a hundred users generates thousands of events a week. Without filtering, the log is technically complete and practically useless.

The second failure is unreadable identifiers. A row saying that user 8f3c2a91 updated resource 44b7 tells an administrator nothing. They then have to go and look up both, in another screen, for every row.

The third is no export. Real investigations happen in a spreadsheet or a security tool, not in your interface. A log you cannot get data out of will be worked around rather than used. Our notes on trust centre pages cover the same gap between what buyers are told exists and what actually works.

How should the table itself be designed?

As a data table, with the established rules applied. Nielsen Norman Group's guidance on data tables, published on 3 April 2022, gives the shape directly.

Freeze the headers: the guidance is to "freeze header rows and header columns (if the table is larger than the screen)." Support scanning: "borders, zebra striping, and hover-triggered highlighting of a record can all help" users keep their place while comparing across rows.

Order columns by importance: "the default order of the columns should reflect the importance of the data to the user and related columns should be adjacent." And critically for audit logs, "the (default) first column should be a human-readable record identifier instead of a 'mystery meat' automatically generated ID." That single rule fixes most audit log tables. Our piece on designing data tables goes into the rest.

What does good filtering look like here?

Nielsen Norman Group's requirement is that "filters need to be discoverable, quick, and powerful" with transparent syntax, and that users have "clear visual indication that filters are active." All three matter more in an audit log than almost anywhere else.

The filters people actually need are narrow: by person, by time range, by action type, and by the specific object. Those four cover the overwhelming majority of real investigations. Everything beyond them is a nice-to-have.

Default the time range to something small, such as the last seven days, and show that default clearly. An audit log that opens on all time is slow to load and immediately overwhelming, and users will assume the slowness is your product rather than the query.

How do you handle retention and volume?

Decide it deliberately and publish it. Retention is the question every security reviewer asks and the one most products answer vaguely. Pick a period, state it on your trust page, and make sure the interface tells users when they are looking at the edge of it.

The volume trap is the one Google's documentation flags for data access logs. Read events dwarf write events in almost every system. If you log every read at the same fidelity as every write, you will generate enormous volume for rows nobody ever queries.

A workable split is to log all writes and permission changes in full, log reads only for sensitive objects, and make the sensitive list configurable. That gives customers with strict requirements what they need without imposing the cost on everyone.

Who is actually reading this screen?

Three people with different jobs, and designing for the wrong one is a common mistake. An administrator debugging a change wants a narrow, recent view. A compliance reviewer wants completeness and export. An incident responder wants to reconstruct a sequence quickly under stress.

The incident responder is the one to design for, because their need is the most demanding and the other two are satisfied along the way. They need to find one event and then see everything around it, which means a way to pivot from a row to its context.

That pivot is the feature most audit logs lack. Clicking a row should let you see everything that actor did that day, or everything that happened to that object. Without it, users are constructing queries by hand during the worst hour of their month.

What should never appear in an audit log?

The contents of what changed, when that content is sensitive. A log entry saying a field was updated is useful. A log entry containing the old and new values of a personal data field turns your audit log into a second, less protected copy of that data.

Credentials, tokens and secrets obviously never appear, but the subtler version is the request payload. Logging full payloads for debugging convenience is how sensitive data leaks into systems with different access rules than the original store.

And avoid logging in a way that lets someone edit history. If administrators can delete audit rows, the log does not do the job it exists for. Append-only is the whole point. Our notes on audit trails for AI automations apply the same principle to automated actors.

How do you know it is working?

Watch whether anyone uses it outside of an audit. A log that only gets opened when a customer is filling in a questionnaire is a compliance artefact, not a product feature. A log that administrators open weekly is doing real work.

Then count the exports. Frequent exporting usually means your filtering is not good enough and people are escaping to a spreadsheet to do the analysis you could have supported.

If you are building or rebuilding an audit log and want a second opinion on the design before it ships, we are happy to walk through it. Come and find us at phoenix.studio.