Sooner or later, a serious customer asks the question: "Can you show us who did what in your system, and when?" For enterprise buyers, healthcare and financial clients, and anyone subject to security audits, the answer determines whether a deal closes. Even for small businesses, audit logs are what let you answer "who changed this invoice?" and "did that employee download the customer list?" This guide explains how to design activity monitoring and audit logging that is useful, trustworthy and proportionate.
Audit logs versus application logs
Application logs help developers debug: errors, stack traces, performance timings. Audit logs are a business record of security-relevant activity: authentication, authorisation, and changes to important data. They serve different audiences (auditors, security teams, customers and support staff), have different retention needs, and require stronger integrity guarantees. Keep them separate, with a stable, documented structure rather than free-text messages.
What to record
- Authentication: successful and failed logins, logouts, multi-factor enrolment and challenges, password changes and resets, session creation and revocation, and single sign-on events. See our access-control guide.
- Authorisation and administration: role and permission changes, invitations, user creation and deactivation, API key creation and revocation, and changes to security settings.
- Data changes: creation, modification and deletion of business-critical records, with before and after values or a diff, and who approved where a workflow requires it.
- Sensitive data access: views and exports of regulated or confidential records, such as health, financial or personal data, since reading can be as significant as writing.
- Exports and bulk operations: downloads, imports, mass updates and deletions.
- System and configuration events: deployments, configuration changes, feature flag changes, integration connections and failures of security controls.
- Support access: when your own staff view a customer account, which enterprise customers increasingly require to be visible to them.
Design the event structure
Use a consistent schema so events are searchable and machine-readable: an event identifier, timestamp in UTC, actor (user or service, with role and tenant), action name from a controlled vocabulary, target resource type and identifier, outcome, source IP address and user agent, a request or correlation identifier that ties events to application traces, and a small structured payload for details. Avoid logging secrets, passwords, tokens or full payment and identity numbers; log references or masked values instead. Decide how to represent changes: storing before and after values is powerful, but careful when those values are themselves sensitive.
Make logs trustworthy
A log that administrators can quietly edit is not evidence. Use write-once or append-only storage where possible, restrict permissions so the application can add entries but not modify or delete them, and ship logs to a separate system or account that application administrators cannot alter. Tamper evidence techniques include hash chaining, where each entry includes a hash of the previous one, and periodic signed checkpoints. Synchronise clocks across servers so sequences make sense. Include the audit system in your backup and recovery plans; see our backup guide.
Retention, privacy and legal considerations
How long you must keep logs depends on regulations, contracts and your own risk assessment, and typical periods range from one to several years, so confirm requirements with your compliance adviser. Balance this against privacy: audit logs contain personal data, so restrict access, limit fields to what is necessary, define retention limits, and handle deletion requests thoughtfully, since some records may need to be retained for legal reasons. We cover the broader obligations in our privacy law guide. This article is general information and not legal advice.
Control who can see the logs
Logs reveal sensitive activity, so apply least privilege: security and compliance roles can search all entries, managers see their team's, and customers see their own tenant's. Log access to the audit log itself. In multi-tenant products, strictly isolate tenants so one customer never sees another's events; the isolation patterns in our white-label architecture article apply.
Alert on what matters
Logs are only useful if someone looks. Define alerts for patterns that indicate risk: many failed logins or logins from unusual locations, privilege escalation, disabling of security controls, access outside working hours, unusually large exports, mass deletions, and access to records by staff with no business reason. Send alerts to the right channel with enough context to act, and tune them to avoid alert fatigue. For larger organisations, forward logs to a security information and event management (SIEM) platform for correlation. See our security audit guide for wider monitoring practices.
Give users a view of their own activity
A good product surfaces some of this to end users: a list of active sessions, recent logins, and security alerts such as "new device signed in." Administrators benefit from an activity feed of changes, filterable by user, record, action and date range, and exportable as CSV for audits. This turns compliance work into a product feature customers value.
Frameworks that ask for it
Security frameworks and regulations commonly expect audit logging and review, including SOC 2, ISO 27001, HIPAA for health information in the United States, PCI DSS for card data and various financial and government standards. Requirements differ, so map your logging to the specific controls that apply to you. Being able to show logging, access reviews and change management evidence shortens vendor security questionnaires considerably.
Implementation approaches
- Define the events and schema with product, security and compliance stakeholders.
- Centralise the code that emits audit events, so developers call one well-tested function instead of writing ad hoc entries.
- Write asynchronously through a reliable queue where appropriate to avoid slowing requests, but guarantee delivery for critical events, and write inside the same transaction for changes that must never be unlogged.
- Store in an append-only, indexed store suitable for search, with archival to cheaper storage for older records.
- Build search and export tools, and test them with realistic investigations.
- Test that logging works as part of the automated test suite and CI, as in our CI/CD article.
Mistakes to avoid
- Logging too little, missing the events an investigation needs, or too much, drowning signal in noise and leaking sensitive data.
- Free-text messages that cannot be queried reliably.
- Letting administrators and developers modify or delete logs.
- Never reviewing the logs or testing the alerts.
- Keeping logs forever with no retention policy, or deleting them too soon.
- Retrofitting late, when the data model cannot support it.
Adding audit trails after the fact is always harder than building them in. Our software team designs audit logging and role-based access into custom applications from the first sprint, and our maintenance plans include log review, alerting and periodic access reviews.
Put this into practice with CodeLuma
CodeLuma builds audit trails, activity reporting and access controls into custom software from the start, so security reviews and compliance audits become a document you export instead of a fire drill.
- Custom software development - tailored systems, integrations and internal tools.
- Maintenance and support plans - updates, monitoring and ongoing improvement.
- Managed hosting - monitored, backed-up, Canadian-friendly hosting.
Start a conversation. Tell us about your project and we will reply with practical next steps, or browse all CodeLuma services. CodeLuma Development Inc. is based in Nova Scotia and works with teams across Canada and remotely.
