Mistakes happen

Mistakes, technical or operational, happen. When they do, you’ll need a way to step through the process and see where and why they happened.

Other times, you might change something manually, because you can’t do it through the interface yet.

And an audit log is useful to see how things changed and where they went wrong

It was also helpful when users have forgotten they’ve changed something. Or perhaps some other team member has.

It’s also useful internally because you can know who made a change. Therefore, you know the correct person to contact to understand why they did it.

It also gives you a different perspective on user interactions. You can see where the changes keep happening. For instance, if the customer frequently triggers the audit log at two different points, you can combine them into one action.

Without an audit log, you still accomplish similar things but with more effort.

It’s very useful for investigating issues

For instance, if the customer thinks that something was changed “automatically”. Checking whether one of their teammates made the change is trivial with the audit log but requires combing through the logs otherwise.

When tracing a bug, you’d have to step through the feature manually. With the audit log, not only is it simpler to do that, but you can even find other occurrences by querying the log entries for similar changes.

A complete audit log tracks changes of entries automatically. It stores the old and the new values and the person who made the change.

It should also track when the application itself made a change, as part of a scheduled task, for instance.

Implementing it is simple

Implementing an audit log is nearly free. Most major frameworks have an extension that does it nearly automatically.

The interface should have a chronological list of changes. The list should include any related (has many) entries as well. The order audit log, for example, shows the changes to the order items also.

It should be easily accessible. That means the link to it is present whenever it might be needed.

Another thing I did was make it accessible through a simple URL change. If the order path is example.com/orders/order-1, the audit log would be example.com/audits/orders/order-1.

Keeping track of deletions and being able to access the page for deleted items is also very helpful. Ideally, you can also un-delete entries as well.

On Rails, the audited gem fulfills all the requirements.

A good role model for this is the Google Docs (and Sheets) revision history. It accomplishes everything on this list and looks good.

But your interface can be much simpler:

But keep an eye on the database size

A potential challenge with running an audit log from the start is that the database would eventually get quite large.

There are two approaches to mitigating this:

First, running it on a dedicated database and web servers.

Secondly, keeping only a limited number of audit-log entries, the last 20, for instance. Some libraries delete older changes, although I do not prefer that approach.

There are also audit log services that you can pay for, but I did not find them cost-effective.