What an admin audit trail should record (and why "who changed this?" should take one search)
Sooner or later a customer writes in: "My plan changed and I did not change it." Without an audit trail, you guess. With a good one, you search, find the change, and answer in a minute.
The fields that matter
- Who. The person or system that made the change. Not "admin". The actual person.
- When. A timestamp in UTC.
- Where. Which product, and which record type and id.
product-two / users / usr_8f2. - What. The named action, like
extend_access, not "updated row". - Before and after. The exact values that changed. This is the field people skip and the one that answers the question.
Why named actions beat raw edits
If admins can edit any column, your log fills with field changes that nobody can interpret later. Named actions carry intent. grant_credits with a before and after of 40 and 65 tells the whole story.
Keep it where you can search it
An audit log you cannot filter by product, person, action, and date is a log nobody reads. Make it exportable too, as CSV or JSON, so a compliance question or a refund dispute is one download.
What not to record
An audit trail is read by more people than the data it describes, so keep secrets out of it. Never write passwords, tokens, API keys, or full card numbers into a before or after. For personal details, record enough to tell records apart, like a masked email, unless you truly need the full value. If a field is sensitive, record that it changed, not what it changed to.
How long to keep it
Keep it at least as long as anyone could reasonably ask about a change. Refund disputes and "why did my plan change?" emails often arrive weeks later. A year covers most questions; some teams keep everything. Whatever you choose, make the audit log append-only, so nobody, including you, can quietly edit history.
Common mistakes
- Logging only failures. The changes that worked are the ones people ask about.
- A shared admin login. If three people use one account, "who" is useless. Give every team member their own login.
- Free text instead of fields. "Gave Dana some credits" cannot be filtered. Store the action, the record, and the values as fields.
- No link to the record. An entry should open the record it changed, so the next question takes one click.
Write it on both sides
If your admin tool calls into your product to make a change, record the change in both places: in the admin tool, and in your product's own table. If either side is ever questioned, the other one agrees.
How LopeBase does it
Every change in LopeBase is a named action with a confirm step. Each one writes an audit event with the team member, product, record, time, and before and after, and the admin adapter in your product writes its own row too. The feed filters by product, person, action, and date, and exports as CSV or JSON. See it in the tour.