Modern applications need to know more than just what data currently looks like. They often need to answer questions such as:
- Who changed this record?
- What was changed?
- When did the change happen?
- What was the previous value?
- What is the new value?
- Which API or service performed the action?
- Was the action performed by a user, administrator, or system process?
This is where audit logs become important.
An audit log provides a historical record of important actions performed inside an application. When designed correctly, audit logging can improve security, debugging, compliance, accountability, and operational visibility.
In this guide, we’ll explore how to design an audit logging system using MongoDB and Node.js, including schema design, change tracking, indexes, middleware, security, and scalable architecture.
What Is an Audit Log?
An audit log is an immutable record of an action performed in an application.
For example, suppose an administrator changes a patient’s status:
User: admin@example.com
Action: UPDATE
Resource: Patient
Resource ID: 65abc123
Changed field: status
Old value: active
New value: inactive
Time: 2026-09-18 12:30:00
Instead of only updating the patient document, the application also creates an audit record.
A simplified audit document might look like:
{
"action": "UPDATE",
"resource": "Patient",
"resourceId": "65abc123",
"userId": "user123",
"timestamp": "2026-09-18T12:30:00.000Z"
}
A production system can store much more information.
Why Do Applications Need Audit Logs?
Audit logs are useful for several reasons.
1. Security
Audit logs help identify suspicious activity.
For example:
User A logged in
User A changed password
User A changed another user's role
User A deleted a record
This creates a timeline of activity.
2. Debugging
Suppose a customer says:
“My profile information changed without my knowledge.”
Without an audit log, finding the source of the change can be difficult.
With audit logging:
10:15 - Profile created
11:30 - Phone number updated
12:05 - Email updated
Developers can investigate exactly what happened.
3. Compliance
Some applications need historical records of data access and changes.
This can be especially important in applications dealing with:
- Healthcare
- Finance
- Insurance
- Enterprise systems
- Government data
Audit logging can help demonstrate who accessed or modified information.
4. Accountability
Audit logs establish a history of actions.
For example:
Administrator A → Created user
Administrator B → Changed role
Administrator A → Disabled account
Audit Logs vs Application Logs
These two concepts are different.
Application log
Application logs are primarily used for debugging and monitoring.
Example:
ERROR: MongoDB connection failed
Audit log
Audit logs record business or security actions.
Example:
User 123 changed role from USER to ADMIN
A useful rule is:
Application logs explain what the system experienced. Audit logs explain what users or system actors did.
What Information Should an Audit Log Store?
A good audit log usually contains the following information.
| Field | Purpose |
|---|---|
_id | Unique audit record |
action | CREATE, UPDATE, DELETE, LOGIN, etc. |
resource | Resource or entity affected |
resourceId | ID of affected document |
userId | Actor who performed the action |
timestamp | Time of the action |
changes | Fields changed |
metadata | Additional context |
ipAddress | Client IP |
userAgent | Client information |
requestId | Request correlation ID |
A more complete document could look like:
{
"_id": "audit123",
"action": "UPDATE",
"resource": "Patient",
"resourceId": "65abc123",
"userId": "user456",
"timestamp": "2026-09-18T12:30:00.000Z",
"changes": {
"status": {
"from": "active",
"to": "inactive"
}
},
"metadata": {
"ipAddress": "192.168.1.20",
"userAgent": "Chrome",
"requestId": "req-789"
}
}
Designing the Audit Log Schema
With MongoDB and Mongoose, you can create a dedicated AuditLog collection.
import { Schema, model, Types } from "mongoose";
const auditLogSchema = new Schema(
{
action: {
type: String,
required: true,
enum: [
"CREATE",
"UPDATE",
"DELETE",
"LOGIN",
"LOGOUT",
"READ",
"EXPORT"
]
},
resource: {
type: String,
required: true
},
resourceId: {
type: Types.ObjectId
},
userId: {
type: Types.ObjectId,
ref: "User"
},
changes: {
type: Schema.Types.Mixed
},
metadata: {
type: Schema.Types.Mixed
},
timestamp: {
type: Date,
default: Date.now
}
},
{
timestamps: true
}
);
export const AuditLog = model("AuditLog", auditLogSchema);
Choosing the Right Audit Actions
Don’t create arbitrary action names throughout the application.
Define centralized constants.
export const AUDIT_ACTION = {
CREATE: "CREATE",
UPDATE: "UPDATE",
DELETE: "DELETE",
LOGIN: "LOGIN",
LOGOUT: "LOGOUT",
READ: "READ",
EXPORT: "EXPORT"
} as const;
This prevents inconsistencies such as:
UPDATE
Updated
update
USER_UPDATED
Instead, the application follows one standard.
Designing the Resource Field
The resource field identifies what was affected.
For example:
Patient
Treatment
CareEpisode
ProductUse
User
Organization
Invoice
Payment
Example:
{
"action": "UPDATE",
"resource": "Treatment",
"resourceId": "65abc123"
}
You can also use constants:
export const AUDIT_RESOURCE = {
USER: "User",
PATIENT: "Patient",
TREATMENT: "Treatment",
CARE_EPISODE: "CareEpisode",
PRODUCT_USE: "ProductUse"
} as const;
Tracking What Changed
One of the most important parts of audit logging is storing the actual changes.
Suppose the original document is:
{
"name": "John",
"status": "active",
"city": "Jaipur"
}
The updated document becomes:
{
"name": "John",
"status": "inactive",
"city": "Delhi"
}
The audit log should ideally store:
{
"status": {
"from": "active",
"to": "inactive"
},
"city": {
"from": "Jaipur",
"to": "Delhi"
}
}
This is much more useful than simply recording:
{
"action": "UPDATE"
}
Creating a Reusable Diff Function
Instead of implementing change detection inside every controller, create a reusable helper.
export function getChanges(
oldData: Record<string, any>,
newData: Record<string, any>
) {
const changes: Record<string, any> = {};
for (const key in newData) {
if (oldData[key] !== newData[key]) {
changes[key] = {
from: oldData[key],
to: newData[key]
};
}
}
return changes;
}
Example:
const oldPatient = {
name: "John",
status: "active",
city: "Jaipur"
};
const newPatient = {
name: "John",
status: "inactive",
city: "Delhi"
};
const changes = getChanges(oldPatient, newPatient);
Result:
{
"status": {
"from": "active",
"to": "inactive"
},
"city": {
"from": "Jaipur",
"to": "Delhi"
}
}
For production systems, this helper should also handle nested objects, arrays, dates, ObjectIds, and normalized values.
Don’t Store Sensitive Data Blindly
Audit logs can accidentally become a second database containing sensitive information.
Avoid storing sensitive fields such as:
password
passwordHash
accessToken
refreshToken
OTP
creditCardNumber
securityAnswer
For example, this is dangerous:
{
"password": {
"from": "oldPassword",
"to": "newPassword"
}
}
Instead, record the action:
{
"action": "PASSWORD_CHANGED",
"resource": "User",
"resourceId": "123"
}
Use a Field Exclusion List
A reusable sanitization function can remove sensitive fields.
const SENSITIVE_FIELDS = [
"password",
"passwordHash",
"accessToken",
"refreshToken",
"otp"
];
function sanitizeChanges(changes: Record<string, any>) {
const sanitized = { ...changes };
for (const field of SENSITIVE_FIELDS) {
delete sanitized[field];
}
return sanitized;
}
Then:
const changes = getChanges(oldData, newData);
const safeChanges = sanitizeChanges(changes);
Recording the User Who Performed the Action
Every user-generated audit event should ideally identify its actor.
For example:
{
"userId": "65abc123",
"action": "UPDATE",
"resource": "Patient"
}
But not every action has a human user.
Some actions may be performed by:
SYSTEM
CRON_JOB
BACKGROUND_WORKER
ADMIN
API_KEY
INTEGRATION
You can support this with an actor model:
actorType: {
type: String,
enum: ["USER", "SYSTEM", "API_KEY"],
required: true
}
And:
actorId: {
type: Schema.Types.ObjectId,
ref: "User"
}
Store Request Information
Request-level metadata can make investigations much easier.
For example:
{
"metadata": {
"ipAddress": "223.178.98.104",
"userAgent": "Mozilla/5.0",
"requestId": "req-12345"
}
}
A requestId is particularly useful.
Suppose your application has:
Request ID: req-12345
You can search application logs and audit logs using the same ID.
This allows you to reconstruct the request flow.
Multi-Tenant Audit Logs
If you’re building a multi-tenant SaaS application, audit logs should also contain the tenant or organization ID.
For example:
{
"tenantId": "tenant123",
"userId": "user456",
"action": "UPDATE",
"resource": "Patient",
"resourceId": "patient789"
}
This is extremely important.
Every audit query must be tenant-aware.
await AuditLog.find({
tenantId,
resource: "Patient"
});
Avoid queries like:
await AuditLog.find({
resource: "Patient"
});
because they could return records belonging to other tenants.
Audit Log Service
Instead of creating audit records directly inside every controller, create an AuditLogService.
interface CreateAuditLogParams {
action: string;
resource: string;
resourceId?: string;
userId?: string;
tenantId?: string;
changes?: Record<string, any>;
metadata?: Record<string, any>;
}
Then:
export async function createAuditLog(
data: CreateAuditLogParams
) {
return AuditLog.create({
...data,
timestamp: new Date()
});
}
Now controllers can simply call:
await createAuditLog({
action: "UPDATE",
resource: "Patient",
resourceId: patient._id.toString(),
userId: req.user.id,
tenantId: req.user.tenantId,
changes,
metadata: {
ipAddress: req.ip,
userAgent: req.headers["user-agent"],
requestId: req.headers["x-request-id"]
}
});
This keeps audit logic centralized.
Example Update API
Consider a patient update endpoint.
const patient = await Patient.findById(patientId);
if (!patient) {
throw new Error("Patient not found");
}
const oldData = patient.toObject();
patient.set(req.body);
await patient.save();
const newData = patient.toObject();
const changes = getChanges(oldData, newData);
if (Object.keys(changes).length > 0) {
await createAuditLog({
action: "UPDATE",
resource: "Patient",
resourceId: patient._id.toString(),
userId: req.user.id,
tenantId: req.user.tenantId,
changes,
metadata: {
ipAddress: req.ip,
userAgent: req.headers["user-agent"]
}
});
}
This gives you a clear sequence:
Fetch old document
↓
Capture old state
↓
Apply changes
↓
Save document
↓
Capture new state
↓
Calculate diff
↓
Create audit log
What About CREATE?
For creation, there is no previous state.
You can store the created fields:
{
"action": "CREATE",
"resource": "Patient",
"resourceId": "123",
"changes": {
"name": {
"from": null,
"to": "John"
},
"status": {
"from": null,
"to": "active"
}
}
}
Or simply store:
{
"action": "CREATE",
"resource": "Patient",
"resourceId": "123"
}
The choice depends on how detailed your audit requirements are.
What About DELETE?
For deletion, you have the opposite problem.
Before deleting:
const patient = await Patient.findById(patientId);
if (!patient) {
throw new Error("Patient not found");
}
const oldData = patient.toObject();
await Patient.deleteOne({
_id: patientId
});
Then record:
{
"action": "DELETE",
"resource": "Patient",
"resourceId": "123"
}
You generally should avoid storing the entire deleted document unless your requirements explicitly need it, because this can duplicate sensitive data.
Don’t Audit Every Database Query
A common mistake is trying to audit every MongoDB operation.
For example:
GET /patients
GET /patients/123
GET /patients/124
GET /patients/125
Logging every read can generate a huge amount of data.
Instead, identify important events.
Examples:
Patient created
Patient updated
Patient deleted
Patient exported
Patient record viewed
Role changed
Password changed
Permission changed
For sensitive systems, read/access logging may be required, but it should be designed intentionally rather than automatically logging every query.
Audit Middleware vs Service
There are two common approaches.
Approach 1: Middleware
Middleware can capture:
Request
User
IP
Endpoint
Response status
Request ID
This is useful for request-level logging.
Example:
app.use(auditMiddleware);
However, middleware usually does not know exactly which database fields changed.
Approach 2: Service-Level Audit
Service-level auditing knows:
Old value
New value
Resource
Business action
Actor
Example:
await patientService.updatePatient();
The service can create the audit event.
Recommended architecture
Use both where appropriate:
Request Middleware
↓
Request Metadata
↓
Controller
↓
Service
↓
Database
↓
Audit Service
MongoDB Indexing for Audit Logs
Audit collections can grow very quickly.
Indexes are therefore important.
A common index is:
auditLogSchema.index({
tenantId: 1,
timestamp: -1
});
This helps retrieve recent audit events for a tenant.
Another useful index:
auditLogSchema.index({
resource: 1,
resourceId: 1,
timestamp: -1
});
This allows queries such as:
await AuditLog.find({
resource: "Patient",
resourceId: patientId
}).sort({
timestamp: -1
});
You may also need:
auditLogSchema.index({
userId: 1,
timestamp: -1
});
The exact indexes should be based on actual audit-query patterns.
Pagination Is Important
Never load thousands of audit records at once.
Avoid:
const logs = await AuditLog.find();
Instead:
const page = 1;
const limit = 20;
const logs = await AuditLog.find({
tenantId
})
.sort({ timestamp: -1 })
.skip((page - 1) * limit)
.limit(limit);
For very large audit collections, cursor-based pagination can be more efficient than large skip() values.
Audit Log Retention
Audit logs can grow continuously.
For example:
1,000 events/day
30,000 events/month
360,000 events/year
Large SaaS applications can generate millions of records.
You therefore need a retention strategy.
Possible strategies include:
Hot audit logs
↓
Recent records in MongoDB
↓
Archive older records
↓
Long-term storage
Depending on requirements, older logs can be moved to archival storage.
MongoDB TTL Indexes
If audit logs only need to exist for a limited period, MongoDB TTL indexes can automatically remove old records.
For example:
auditLogSchema.index(
{ createdAt: 1 },
{ expireAfterSeconds: 60 * 60 * 24 * 365 }
);
This example retains records for approximately one year.
However, do not use TTL indexes for audit logs that must be retained indefinitely or for a legally/compliance-required retention period.
Make Audit Logs Immutable
An audit log should generally be treated as append-only.
Applications should:
CREATE audit event
but normally should not:
UPDATE audit event
DELETE audit event
A good architectural rule is:
Audit records describe history and should not be rewritten to change that history.
Access to audit logs should also be restricted.
For example:
Normal User
↓
No audit access
Manager
↓
Limited audit access
Administrator
↓
Audit access
The exact authorization model depends on the application.
Protect Audit Logs From Tampering
For high-security systems, simply storing audit records in MongoDB may not be enough.
Consider:
- Restricted database permissions
- Separate audit collection
- Separate database
- Append-only application permissions
- Backups
- Immutable archival storage
- Access monitoring
- Hash chaining or digital signatures for high-assurance environments
For example, an event could contain:
{
"eventHash": "...",
"previousEventHash": "..."
}
This can help detect modification of the event sequence.
Such mechanisms add complexity and should be introduced when the threat model or compliance requirements justify them.
Don’t Trust Client-Supplied User IDs
Never allow the frontend to send:
{
"userId": "admin123"
}
and blindly use it for the audit record.
Instead, obtain the actor identity from your authenticated server-side context:
const userId = req.user.id;
The server should determine:
Who performed the action?
not the client.
Audit Failed Actions Too
Successful actions aren’t the only useful events.
For security-sensitive operations, failed attempts can also be valuable.
For example:
{
"action": "LOGIN_FAILED",
"resource": "User",
"userId": "123",
"metadata": {
"ipAddress": "192.168.1.10"
}
}
Other examples:
PASSWORD_CHANGE_FAILED
PERMISSION_DENIED
EXPORT_FAILED
DELETE_DENIED
LOGIN_FAILED
This can help identify suspicious activity.
Avoid Logging Secrets
Be careful with request logging.
Never put these directly into audit metadata:
Authorization header
JWT
Refresh token
Password
OTP
API secret
Encryption key
Bad:
metadata: {
headers: req.headers
}
This could accidentally store:
Authorization: Bearer eyJ...
Cookie: ...
Instead, explicitly select safe metadata:
metadata: {
ipAddress: req.ip,
userAgent: req.headers["user-agent"],
requestId: req.headers["x-request-id"]
}
Audit Logs and MongoDB Transactions
For critical operations, you may want the business update and audit event to succeed together.
For example:
Update Patient
+
Create Audit Log
Both can be performed inside a MongoDB transaction.
const session = await mongoose.startSession();
try {
session.startTransaction();
await Patient.updateOne(
{ _id: patientId },
{ $set: updateData },
{ session }
);
await AuditLog.create(
[
{
action: "UPDATE",
resource: "Patient",
resourceId: patientId,
userId,
changes
}
],
{ session }
);
await session.commitTransaction();
} catch (error) {
await session.abortTransaction();
throw error;
} finally {
await session.endSession();
}
Now the application avoids a situation where the patient update succeeds but the audit event fails.
When Should You Use a Transaction?
Transactions are particularly useful when the audit record is considered part of the same critical operation.
For example:
Financial transaction
+
Audit event
or:
Permission change
+
Audit event
However, transaction usage should be balanced against performance and architecture requirements.
For high-volume, non-critical telemetry, asynchronous event processing may be more appropriate.
Synchronous vs Asynchronous Audit Logging
There are two common architectures.
Synchronous
API Request
↓
Update Database
↓
Create Audit Log
↓
Return Response
Advantages:
- Simple
- Audit event is immediately available
- Can use a transaction
Disadvantages:
- Adds latency
- Audit failure can affect the main operation
Asynchronous
API Request
↓
Update Database
↓
Publish Audit Event
↓
Queue
↓
Audit Worker
↓
MongoDB
Advantages:
- Lower request latency
- Better scalability
- Audit processing can be retried
Disadvantages:
- More infrastructure
- Eventual consistency
- More failure scenarios to handle
For high-volume systems, an event-driven approach can be useful.
Example Audit Event
A production-style audit event might look like:
{
"tenantId": "tenant_123",
"actor": {
"type": "USER",
"userId": "user_456"
},
"action": "UPDATE",
"resource": "Patient",
"resourceId": "patient_789",
"changes": {
"status": {
"from": "active",
"to": "inactive"
}
},
"metadata": {
"requestId": "req_123",
"ipAddress": "192.168.1.10",
"userAgent": "Chrome"
},
"timestamp": "2026-09-18T12:30:00.000Z"
}
This structure provides enough context to investigate the event without storing unnecessary information.
Recommended Project Structure
For a Node.js + TypeScript application:
src/
│
├── modules/
│ ├── patient/
│ │ ├── patient.model.ts
│ │ ├── patient.service.ts
│ │ └── patient.controller.ts
│ │
│ └── audit/
│ ├── audit.model.ts
│ ├── audit.interface.ts
│ ├── audit.service.ts
│ ├── audit.constant.ts
│ └── audit.helper.ts
│
├── middleware/
│ ├── auth.middleware.ts
│ └── request-id.middleware.ts
│
└── utils/
└── diff.helper.ts
This keeps audit functionality reusable across modules.
Recommended Audit Flow
A clean architecture looks like this:
Client
│
▼
Authentication
│
▼
Request Middleware
│
┌────────┴────────┐
│ │
▼ ▼
Controller Request ID
│
▼
Service
│
├───────────────┐
│ │
▼ ▼
MongoDB Diff Helper
│ │
└───────┬───────┘
▼
Audit Service
│
▼
Audit Logs
Common Audit Logging Mistakes
1. Logging Everything
Not every database operation needs an audit event.
2. Storing Passwords or Tokens
Never store secrets in audit records.
3. No Actor Information
An audit event without an actor is often difficult to investigate.
4. No Tenant ID
Multi-tenant applications should associate audit events with the appropriate tenant.
5. No Indexes
Audit collections can become very large.
6. No Pagination
Never return an entire audit collection from an API.
7. Allowing Audit Records to Be Edited
Audit history should generally be append-only.
8. Putting Audit Logic Everywhere
Avoid duplicating:
AuditLog.create(...)
throughout dozens of controllers.
Use a centralized audit service.
9. Trusting Client Data
Don’t allow the frontend to determine:
actorId
tenantId
without server-side validation and authorization.
Best Practices Checklist
Before deploying an audit logging system, consider:
- Store audit logs in a dedicated collection.
- Record the action.
- Record the affected resource.
- Record the resource ID.
- Record the actor.
- Record the tenant ID for multi-tenant systems.
- Store meaningful changes for updates.
- Remove sensitive fields.
- Never store passwords or tokens.
- Add request IDs.
- Capture useful request metadata.
- Add indexes based on query patterns.
- Implement pagination.
- Define a retention policy.
- Restrict access to audit logs.
- Treat audit logs as append-only.
- Consider transactions for critical operations.
- Consider asynchronous processing for high-volume systems.
- Monitor audit storage growth.
- Test tenant isolation.
- Test authorization around audit-log access.
Final Thoughts
A well-designed audit logging system is more than a collection that stores:
user + action + timestamp
A useful audit system answers:
Who?
What?
When?
Which resource?
What changed?
From what value?
To what value?
From which request?
From which tenant?
For a Node.js and MongoDB application, a strong design typically consists of:
Dedicated AuditLog collection
+
Centralized Audit Service
+
Reusable Change Detection
+
Sensitive Data Sanitization
+
Tenant Isolation
+
Proper Indexing
+
Access Control
+
Retention Strategy
Start with a simple, consistent audit schema, and evolve toward asynchronous processing, archival storage, tamper detection, and stronger guarantees as your application’s scale and security requirements increase.
