NestJS Context Logger
[](https://badge.fury.io/js/nestjs-context-logger)
[](https://opensource.org/licenses/MIT)
🌟 A contextual logger for NestJS applications. 🌟
Enrich your logs with custom context, whenever and wherever you want in your request lifecycle.
[Quick Start](#quick-start) •
[API Reference](#api-reference) •
[Best Practices](#best-practices) •
[FAQ](#faq) •
[Contributing](#contributing) •
[License](#license)
> 🔍 Ever tried debugging a production issue with logs like `"Error updating user"` but no context about which user, service, or request caused it? **This logger is your solution.**
# Overview
nestjs-context-logger is a structured, contextual, logging solution for NestJS applications that enables you to enrich your logs with custom context, whenever and wherever you want in NestJS request execution lifecycle.
```typescript
// Traditional logging 😢
logger.error('Failed to update user subscription');
// Output: {"level":"error","message":"Failed to update user subscription"}
// With nestjs-context-logger 🎉
logger.error('Failed to update user subscription');
// Output: {
// "level":"error",
// "message":"Failed to update user subscription",
// "correlationId":"d4c3f2b1-a5e6-4c3d-8b9a-1c2d3e4f5g6h",
// "userId":"user_456",
// "subscriptionTier":"premium",
// "service":"SubscriptionService",
// "requestPath":"/api/subscriptions/update",
// "duration": 432,
// "timestamp":"2024-01-01T12:00:00Z"
// }
```
# Installation
```bash
npm install nestjs-context-logger
```
# Quick Start
```typescript
// app.module.ts
import { ContextLoggerModule } from 'nestjs-context-logger';
@Module({
imports: [
ContextLoggerModule.forRoot()
],
})
export class AppModule {}
```
That's it! Your logs will automatically include the default context of `correlationId` and `duration`.
# Why nestjs-context-logger?
[](https://medium.com/elementor-engineers/implement-contextual-logging-in-nestjs-using-asyncstorage-eb228bf00008)
- 🎯 **Developer experience**: Easy to use, zero code changes required, keep using the familiar `@nestjs/common` logger interface.
- ⚡ **High Performance**: Built on Pino, one of the fastest loggers in the Node.js ecosystem
- 📊 **Default Context**: Automatically enriches request with `correlationId` and `duration`
- 🚀 **Platform agnostic**: works with `Express` and `Fastify`
- ✅ **Automatic context cleanup**: Memory is cleaned up and garbage collected when request cycle ends
# Advanced Configuration
## Automatic context enrichment via configuration
You can enrich your logs with custom context at the application level:
```typescript
@Module({
imports: [
ContextLoggerModule.forRootAsync({
imports: [ConfigModule],
inject: [ConfigService],
useFactory: (configService: ConfigService) => ({
pinoHttp: {
level: configService.get('LOG_LEVEL'),
},
// enrichContext intercepts requests and allows you to enrich the context
enrichContext: async (context: ExecutionContext) => ({
userId: context.switchToHttp().getRequest().user?.id,
tenantId: context.switchToHttp().getRequest().headers['x-tenant-id'],
environment: configService.get('NODE_ENV'),
}),
}),
});
],
})
export class AppModule {}
```
Now every log will include these additional fields:
```typescript
// Output: {
// "message": "Some log message",
// "userId": "user_123",
// "tenantId": "tenant_456",
// "environment": "production",
// ...other default fields
// }
```
## Log Field Grouping
You can group different types of log fields under specific keys, making logs more organized and easier to query:
```typescript
ContextLoggerModule.forRoot({
groupFields: {
bindingsKey: 'params', // Groups runtime bindings
contextKey: 'metadata' // Groups context information
}
})
```
Before grouping:
```json
{
"userId": "123", // context field
"requestId": "abc", // context field
"correlationId": "xyz", // binding
"timestamp": "...", // binding
"level": "info",
"msg": "User logged in"
}
```
After grouping:
```json
{
"metadata": { // grouped context
"userId": "123",
"requestId": "abc"
},
"params": { // grouped bindings
"correlationId": "xyz",
"timestamp": "..."
},
"level": "info",
"msg": "User logged in"
}
```
## Context Adaptation
Transform context data before logging to standardize format, remove sensitive data, or add computed fields:
```typescript
ContextLoggerModule.forRoot({
contextAdapter: (context) => ({
...context,
sensitive: undefined, // Remove sensitive data
requestId: context.reqId, // Rename fields
timestamp: Date.now() // Add new fields
})
})
```
## Bootstrap Logs Control
Control NestJS framework bootstrap logs to reduce noise during startup:
```typescript
ContextLoggerModule.forRoot({
ignoreBootstrapLogs: true // Suppress framework bootstrap logs
})
```
## Add custom context from anywhere
Update context from anywhere in the code 🎉. The context persists throughout the entire request execution, making it available to all services and handlers within that request.
For example, set up user context in a guard:
```typescript
@Injectable()
export class ConnectAuthGuard implements CanActivate {
private readonly logger = new ContextLogger(ConnectAuthGuard.name);
async canActivate(context: ExecutionContext): Promise