An audit trail should help an authorised reviewer reconstruct an important action: who or what initiated it, what record changed, when it happened, what the result was and which business context explains it. A long table of technical messages does not automatically provide that evidence. Neither does a history screen that users can alter with the same permissions as the record it describes.
For a Kenyan or East African organisation planning custom software, a dashboard, an integration or workflow automation, audit requirements belong in discovery. They affect the data model, permissions, storage, privacy, operations and acceptance tests. This guide gives business owners, operations teams, risk leads and developers a practical brief to agree before implementation. It is general planning guidance, not a statement that one retention period or control fits every organisation.
Bring one workflow and the decisions that must be reconstructable.
Share event types, roles, approval boundaries and review needs. Do not send production exports, credentials, access tokens or identifiable customer and staff records in an initial enquiry.
Discuss the audit brief Explore custom software developmentAudit trail, application log and change history are not the same
A change history helps a user understand revisions to one record. An operational log helps teams diagnose jobs, errors and performance. A security log helps detect and investigate security events. An audit trail is evidence designed around a review question, such as whether an approval followed authority limits or who exported a customer dataset.
The records may share an event pipeline, but their purpose, audience, detail and retention can differ. Mixing everything into one unrestricted log makes review harder and increases the chance of storing sensitive information without a clear reason.
Start with a one-page audit-event matrix
List the business events down the rows, then define the evidence and control fields across the columns. The matrix should be understandable to the person who owns the workflow, not only to developers.
| Event | Actor | Affected record | Evidence | Reviewer | Response |
|---|---|---|---|---|---|
| Request approved | User or service identity | Stable request reference | Decision, previous state, new state, authority context | Process owner | Investigate exceptions |
| Role changed | Access administrator | User and role references | Role added or removed, approver, reason reference | Access owner | Revoke or correct |
| Data exported | User or integration | Export job reference | Dataset class, filters, record count, result | Data owner | Escalate unusual export |
This is an illustrative structure. Replace events, reviewers, thresholds and responses with the organisation’s real policy, contractual duties and risk. Do not copy personal data into the trail merely because it appears in the business record.
12 decisions to make before implementation
1. Define the questions the trail must answer
Begin with review questions, not database columns. Examples include: who approved this payment, why did this record reopen, which account changed a customer’s delivery address, what did an integration submit and which export contained a class of records? Each question identifies the events and context that matter.
If nobody can name a future reviewer or decision, challenge whether the event belongs in an audit trail. Logging everything creates noise and storage cost without guaranteeing useful evidence.
2. Select business and security events deliberately
Common candidates include sign-in outcomes, role assignments, privileged configuration, create-update-delete actions, approvals, reversals, refunds, exports, imports, consent or preference changes, integration credential changes and audit-setting changes. The exact list depends on the workflow.
Record failed high-risk actions as well as successful ones where they help detect misuse or diagnose access rules. Do not exclude an event simply because it came from an administrator or a trusted integration.
3. Identify human and machine actors
Use a stable internal actor reference and actor type. Distinguish staff, customers, background jobs, service accounts and external integrations. A shared username such as “admin” weakens attribution; named accounts and scoped service identities make later review more meaningful.
Store a display label only when it is necessary for the reviewer, and expect names to change. The durable identity should not depend on mutable email addresses or job titles.
4. Record when, where, what and result
A useful event normally needs a server-side timestamp with timezone, application or service, event type, actor reference, affected resource, action, result and correlation reference. Add a reason or authority context when the workflow uses it. For distributed systems, record both the business-event time and ingestion time when delays are possible.
Use consistent event names and documented field formats. Free-text messages alone are difficult to filter, test and reconcile across web, mobile, API and background jobs.
5. Capture before-and-after evidence proportionately
For a material change, reviewers may need the previous and new values—or a safe representation of the changed fields. A full copy of the record can be excessive, especially where the record contains personal, financial or confidential data.
Define which fields need exact values, which can be masked, which need only a change flag and which should never enter the log. A stable version number or hash can support integrity checks without duplicating every field.
6. Keep secrets and unnecessary personal data out
Passwords, access tokens, private keys, session identifiers, connection strings and full payment credentials do not belong in an audit event. Sensitive personal data and ordinary personal identifiers also need a clear purpose, access boundary and retention decision before they are recorded.
Kenya’s data-protection framework includes purpose limitation, data minimisation, security safeguards and retention limits for personal data. If an audit trail contains personal data, document the lawful purpose and obtain qualified advice for the organisation’s specific obligations.
7. Make audit records tamper-evident
Ordinary users should not be able to edit or delete their own audit records. Separate write and read permissions, restrict administrative access and record access to the trail where risk warrants it. Consider append-only storage, integrity hashes, immutable copies or a protected central log service according to the architecture and threat model.
Tamper-evident does not mean impossible to delete forever. The design still needs authorised retention and disposal processes; those operations should themselves produce reviewable evidence.
8. Define retention by purpose
Avoid choosing “keep everything forever” as a substitute for analysis. Map each event class to its purpose, legal or contractual basis where applicable, review frequency, retention period and disposal action. Security incident evidence, financial approvals and low-value technical diagnostics may justify different periods.
Backups and exported copies belong in the retention design too. Deleting an online record while leaving uncontrolled copies in archives does not complete the disposal decision.
9. Control who can search and export the trail
Audit data can reveal staff activity, customer references, system structure and exception patterns. Define who may view, search, export and administer it. Separate operational review from unrestricted database access, and mask fields that a reviewer does not need.
Exports need their own audit event, a clear purpose and safe delivery method. Do not send audit evidence through ordinary chat simply because a stakeholder asks for a quick copy.
10. Design review, alerts and ownership
A trail nobody reviews is only stored data. Name the process owner, security or risk reviewer, review frequency, exception criteria and response path. Use alerts selectively for events that need timely action, such as privileged role changes or unusually large exports.
Record the investigation reference and resolution without rewriting the original event. Review evidence should show what was considered and what action followed.
11. Connect events across systems
When a workflow crosses an application, payment service, email provider or other API, use a safe correlation or operation reference. It should let a reviewer follow the business action without placing credentials or personal data in URLs and log messages.
Agree which system is authoritative for each outcome. A sent request, accepted response and completed business transaction are different events; one success message does not prove the entire workflow reconciled.
12. Test the evidence, not only the screen
Acceptance tests should cover successful and denied actions, retries, duplicate requests, failed integrations, role changes, timezones, edited records, export controls, log-storage failure and authorised disposal. For each scenario, verify that the expected event is present once, sensitive fields are absent and the reviewer can reconstruct the result.
Also test failure safely. The main transaction should follow an explicit policy when audit storage is unavailable; silent evidence loss is not a dependable default.
An audit-trail acceptance checklist
- Every event supports a named review question and owner.
- Human and machine actors use stable, distinguishable references.
- Timestamps, event names, resources, actions and results follow documented formats.
- Before-and-after evidence is sufficient without copying unnecessary data.
- Secrets, tokens and prohibited fields are removed or safely transformed.
- Users cannot alter evidence for their own actions.
- Retention and disposal are defined by purpose and include backups and exports.
- Viewing, searching and exporting the trail use explicit permissions.
- Review schedules, alert thresholds and escalation owners are named.
- Correlation references connect system boundaries without exposing sensitive data.
- Log access, administration and disposal create their own evidence where required.
- Positive, negative, retry and failure tests prove the trail is usable.
Connect audit evidence to the wider system design
Audit events depend on the roles allowed to act. Use the permission-matrix guide to define those boundaries, then connect the events to the workflow controls and exception paths. The API integration guide helps define correlation, retries and reconciliation across systems.
If the system is still being scoped, place audit evidence beside users, data and acceptance criteria using the MVP scope checklist. For an existing platform, the software handover guide helps identify access, history, backups and operational ownership before changes begin.
Frequently asked questions
What should a software audit trail record?
Record enough to reconstruct the intended event: when and where it occurred, the human or machine actor, the action, affected resource, result, correlation reference and necessary business context. The exact fields should follow the review purpose.
Should an audit trail store every old and new value?
Not automatically. Capture the evidence needed for review while excluding secrets and unnecessary personal or confidential data. Some fields need exact before-and-after values; others may need a mask, hash, version or change flag.
Can administrators edit audit records?
Ordinary application and business administrators should not be able to rewrite evidence for their actions. Use separated permissions and tamper-evident storage, with authorised retention or disposal operations recorded where appropriate.
How long should audit logs be kept in Kenya?
There is no single period for every system. Define retention from the event’s purpose and applicable legal, regulatory and contractual requirements. When logs contain personal data, apply purpose limitation and retain it only as long as reasonably necessary unless another lawful basis applies.
Can Rx Code Labs add an audit trail to an existing system?
Often, yes. We first review the workflows, data model, identities, permissions, integrations, existing logs, hosting and review needs before proposing a safe implementation or improvement scope.
Define the audit-event matrix before development.
Bring one workflow, the decisions that matter, the actors involved, sensitive fields and the people who will review exceptions. We can map the open questions and shape a reviewable system scope.
Plan the audit event matrix Explore dashboards and workflow automation Use the contact page