@infineit/winston-logger 1.0.31 → 1.0.32

package/README.md

@@ -6,10 +6,11 @@ Enterprise-level logging library for NestJS applications with support for multip
 
 - ✅ **Multi-Context Support**: Works in HTTP services, Kafka consumers, Bull/BullMQ workers, CRON jobs, and CLI tasks
 - ✅ **Transport Architecture**: Pluggable transport system with Winston as one transport among many
+- ✅ **Optional Central Forwarding**: Forward logs to centralized logging service via HTTP or Kafka (optional, fire-and-forget)
 - ✅ **Log Normalization**: Automatic normalization and error serialization before transport
 - ✅ **CLS Integration**: Correlation ID support via AsyncLocalStorage (CLS)
 - ✅ **Fire-and-Forget**: Non-blocking, failure-safe logging that never breaks business logic
-- ✅ **Zero Dependencies**: No database, HTTP framework, or ORM dependencies
+- ✅ **Zero Dependencies**: No database, HTTP framework, or ORM dependencies (HTTP forwarding uses built-in Node.js modules)
 - ✅ **Type-Safe**: Full TypeScript support with comprehensive type definitions
 
 ## Table of Contents
@@ -20,8 +21,12 @@ Enterprise-level logging library for NestJS applications with support for multip
 - [Configuration](#configuration)
 - [Usage in Different Contexts](#usage-in-different-contexts)
 - [Transport Architecture](#transport-architecture)
+- [Central Log Forwarding](#central-log-forwarding)
 - [Log Normalization](#log-normalization)
 - [Correlation ID (CLS)](#correlation-id-cls)
+  - [CLS Context Boundaries and Edge Cases](#cls-context-boundaries-and-edge-cases)
+  - [Correlation ID Format Validation](#correlation-id-format-validation)
+- [Complete Integration Examples](#complete-integration-examples)
 - [API Reference](#api-reference)
 - [Migration Guide (Legacy app.useLogger Users)](#migration-guide-legacy-appuselogger-users)
 - [Best Practices](#best-practices)
@@ -169,6 +174,11 @@ const config: LoggerModuleConfig = {
   organization: 'my-org',             // Organization name (optional)
   context: 'user-service',            // Bounded context name (optional)
   app: 'api-gateway',                 // Application name (optional)
+  // Optional: Central log forwarding (disabled by default)
+  forwardToCentral: false,            // Enable forwarding to centralized logging service
+  transportType: 'http',              // 'http' or 'kafka' (required if forwardToCentral=true)
+  httpEndpoint: 'https://...',        // HTTP endpoint (required if transportType='http')
+  // kafkaTopic: 'project-logs',      // Kafka topic (required if transportType='kafka')
 };
 
 @Module({
@@ -192,6 +202,14 @@ LOG_IN_FILE=true
 LOGGER_ORGANIZATION=my-org
 LOGGER_CONTEXT=user-service
 LOGGER_APP=api-gateway
+
+# Optional: Central log forwarding (disabled by default)
+LOGGER_FORWARD_TO_CENTRAL=false
+LOGGER_TRANSPORT_TYPE=http
+LOGGER_HTTP_ENDPOINT=https://logging-service.example.com/api/logs
+# OR for Kafka:
+# LOGGER_TRANSPORT_TYPE=kafka
+# LOGGER_KAFKA_TOPIC=project-logs-sales
 ```
 
 ```typescript
@@ -206,6 +224,11 @@ export default registerAs('logger', () => ({
   organization: process.env.LOGGER_ORGANIZATION,
   context: process.env.LOGGER_CONTEXT,
   app: process.env.LOGGER_APP,
+  // Optional: Central log forwarding
+  forwardToCentral: process.env.LOGGER_FORWARD_TO_CENTRAL,
+  transportType: process.env.LOGGER_TRANSPORT_TYPE,
+  httpEndpoint: process.env.LOGGER_HTTP_ENDPOINT,
+  kafkaTopic: process.env.LOGGER_KAFKA_TOPIC,
 }));
 ```
 
@@ -233,12 +256,52 @@ export class AppModule {}
 | `organization` | `string` | No | `undefined` | Organization or project name |
 | `context` | `string` | No | `undefined` | Bounded context name |
 | `app` | `string` | No | `undefined` | Application or microservice name |
+| `forwardToCentral` | `boolean \| string` | No | `false` | Enable forwarding to centralized logging service (`true`/`false` or `'true'`/`'false'`) |
+| `transportType` | `'kafka' \| 'http'` | No | `undefined` | Transport type for central forwarding (required if `forwardToCentral=true`) |
+| `httpEndpoint` | `string` | No | `undefined` | HTTP endpoint for central forwarding (required if `transportType='http'`) |
+| `kafkaTopic` | `string` | No | `undefined` | Kafka topic for central forwarding (required if `transportType='kafka'`) |
 
 ### Default Behavior
 
 - **Development/Testing**: Console and file logging enabled by default
 - **Production**: Console and file logging disabled by default (unless explicitly enabled)
 - **Slack**: Only enabled in production/testing when `slack_webhook` is provided
+- **Central Forwarding**: Disabled by default (set `forwardToCentral=true` to enable)
+
+### Environment-Specific Configuration Tips
+
+**Development:**
+```bash
+# Disable forwarding in development (optional)
+LOGGER_FORWARD_TO_CENTRAL=false
+# OR use local endpoint for testing
+LOGGER_FORWARD_TO_CENTRAL=true
+LOGGER_TRANSPORT_TYPE=http
+LOGGER_HTTP_ENDPOINT=http://localhost:3000/api/logs
+```
+
+**Production:**
+```bash
+# Enable forwarding in production
+LOGGER_FORWARD_TO_CENTRAL=true
+LOGGER_TRANSPORT_TYPE=http
+LOGGER_HTTP_ENDPOINT=https://central-logging.example.com/api/logs
+# OR use Kafka for better performance
+# LOGGER_TRANSPORT_TYPE=kafka
+# LOGGER_KAFKA_TOPIC=project-logs-<project-name>
+```
+
+**Project-Specific Topics (Kafka):**
+```bash
+# Sales project
+LOGGER_KAFKA_TOPIC=project-logs-sales
+
+# Document project
+LOGGER_KAFKA_TOPIC=project-logs-document
+
+# Common service
+LOGGER_KAFKA_TOPIC=project-logs-common
+```
 
 ---
 
@@ -509,6 +572,195 @@ All transports must:
 
 ---
 
+## Central Log Forwarding
+
+### Overview
+
+The logger can optionally forward all logs to a centralized logging microservice via HTTP or Kafka. This is an **optional feature** that runs alongside existing logging (console, file, Slack) without modifying or affecting it.
+
+**Key characteristics:**
+- ✅ **Optional**: Only enabled when `forwardToCentral=true` (disabled by default)
+- ✅ **Fire-and-forget**: Non-blocking, never throws, failures are swallowed
+- ✅ **Preserves correlationId**: Automatically includes correlationId from CLS
+- ✅ **Non-invasive**: Original logging (console, file, Slack) continues normally and is unaffected
+
+### Configuration
+
+**Via Environment Variables:**
+```bash
+LOGGER_FORWARD_TO_CENTRAL=true
+LOGGER_TRANSPORT_TYPE=http
+LOGGER_HTTP_ENDPOINT=https://logging-service.example.com/api/logs
+# OR for Kafka:
+# LOGGER_TRANSPORT_TYPE=kafka
+# LOGGER_KAFKA_TOPIC=project-logs-sales
+```
+
+**Via Module Configuration:**
+```typescript
+@Module({
+  imports: [
+    LoggerModule.forRoot({
+      // ... existing config
+      forwardToCentral: true,
+      transportType: 'http', // or 'kafka'
+      httpEndpoint: 'https://logging-service.example.com/api/logs',
+      // OR for Kafka:
+      // kafkaTopic: 'project-logs-sales',
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### HTTP Forwarding
+
+Forwards logs via HTTP POST requests to the configured endpoint. Uses Node.js built-in `http`/`https` modules (no external dependencies).
+
+**Configuration:**
+```bash
+LOGGER_FORWARD_TO_CENTRAL=true
+LOGGER_TRANSPORT_TYPE=http
+LOGGER_HTTP_ENDPOINT=https://central-logging.example.com/api/logs
+```
+
+**Usage:** No code changes required. All logs are automatically forwarded with correlationId preserved.
+
+**Request Format:**
+- **Method**: POST
+- **Headers**: `Content-Type: application/json`, `x-correlation-id: <correlationId>` (if available)
+- **Body**: `NormalizedLog` JSON object
+
+### Kafka Forwarding
+
+Forwards logs to a configured Kafka topic. Requires a Kafka producer instance provided by your application.
+
+**Prerequisites:** Provide Kafka producer via `KafkaProducerKey`:
+
+```typescript
+import { Module, Provider } from '@nestjs/common';
+import { Kafka } from 'kafkajs';
+import { LoggerModule, KafkaProducerKey } from '@infineit/winston-logger';
+
+@Module({
+  imports: [
+    LoggerModule.forRoot({
+      forwardToCentral: true,
+      transportType: 'kafka',
+      kafkaTopic: 'project-logs-sales',
+    }),
+  ],
+  providers: [
+    {
+      provide: KafkaProducerKey,
+      useFactory: async () => {
+        const kafka = new Kafka({ brokers: ['localhost:9092'] });
+        const producer = kafka.producer();
+        await producer.connect();
+        return producer;
+      },
+    },
+  ],
+})
+export class AppModule {}
+```
+
+**Usage:** No code changes required. All logs are automatically forwarded with correlationId preserved.
+
+**Message Format:**
+- **Topic**: Configured `kafkaTopic`
+- **Key**: `correlationId` or `'no-correlation-id'` if not available
+- **Headers**: `x-correlation-id: <correlationId>` (if available)
+- **Value**: `NormalizedLog` JSON string
+
+### Correlation ID Preservation
+
+Correlation ID is automatically preserved and forwarded:
+
+**HTTP Forwarding:**
+1. Correlation ID from CLS is included in log normalization
+2. Forwarder sends log with `correlationId` in HTTP header (`x-correlation-id`) and body
+
+**Kafka Forwarding:**
+1. Correlation ID from CLS is included in log normalization
+2. Forwarder sends log with `correlationId` as message key, header, and in message value
+
+**No changes required:** If CLS is configured, correlationId is automatically included in forwarded logs.
+
+### Fire-and-Forget Behavior
+
+Central log forwarding is completely fire-and-forget:
+
+- ✅ **Never blocks**: Forwarding happens asynchronously, never blocks business logic
+- ✅ **Never throws**: All errors are swallowed, never propagate to application code
+- ✅ **Never affects business logic**: Forwarding failures are logged to `console.error` only
+- ✅ **Never breaks logging**: Original logging (console, file, Slack) continues normally and is unaffected
+
+**Important:** Original logging behavior remains completely unchanged. Forwarding is an additional, optional layer that runs in parallel.
+
+### Environment-Specific Configuration
+
+**Development:**
+```bash
+# Option 1: Disable forwarding in development
+LOGGER_FORWARD_TO_CENTRAL=false
+
+# Option 2: Use local endpoint for testing
+LOGGER_FORWARD_TO_CENTRAL=true
+LOGGER_TRANSPORT_TYPE=http
+LOGGER_HTTP_ENDPOINT=http://localhost:3000/api/logs
+```
+
+**Production:**
+```bash
+# HTTP forwarding (simpler setup)
+LOGGER_FORWARD_TO_CENTRAL=true
+LOGGER_TRANSPORT_TYPE=http
+LOGGER_HTTP_ENDPOINT=https://central-logging.example.com/api/logs
+
+# OR Kafka forwarding (better performance, requires Kafka producer)
+LOGGER_FORWARD_TO_CENTRAL=true
+LOGGER_TRANSPORT_TYPE=kafka
+LOGGER_KAFKA_TOPIC=project-logs-<project-name>
+```
+
+**Project-Specific Topics (Kafka):**
+Use different Kafka topics per project for better log organization:
+```bash
+# Sales project
+LOGGER_KAFKA_TOPIC=project-logs-sales
+
+# Document project
+LOGGER_KAFKA_TOPIC=project-logs-document
+
+# Common service
+LOGGER_KAFKA_TOPIC=project-logs-common
+```
+
+### Troubleshooting
+
+**Forwarding Not Working:**
+1. Check configuration: `LOGGER_FORWARD_TO_CENTRAL` must be `'true'` or `true`
+2. Verify transport type: Must be `'http'` or `'kafka'`
+3. Check endpoint/topic: Must be configured correctly
+4. For Kafka: Ensure `KafkaProducerKey` is provided in module providers
+5. Check console errors: Forwarding errors are logged to `console.error` with message `"CentralLogForwarder forward error (swallowed): <error>"`
+
+**Correlation ID Missing:**
+- Ensure CLS is configured: `ClsModule.forRoot()` with `generateId: true`
+- Ensure `ContextModule` is imported
+- Check that original logs have `correlationId` field (if not, forwarded logs won't either)
+
+**HTTP Forwarding Timeout:**
+- HTTP forwarding has a 5-second timeout
+- Timeouts are swallowed (no errors thrown)
+- Consider using Kafka instead if central service is slow
+- Or improve central service performance
+
+**Note:** Forwarding failures do not affect your application. Original logging continues normally, and business logic is never impacted.
+
+---
+
 ## Log Normalization
 
 ### Automatic Normalization
@@ -649,6 +901,732 @@ import { v4 as uuidv4 } from 'uuid';
 export class AppModule {}
 ```
 
+### CLS Context Boundaries and Edge Cases
+
+#### Async Context Propagation
+
+CLS (AsyncLocalStorage) automatically propagates correlation ID within the same async context chain:
+
+```typescript
+// ✅ Works: Same async context
+async handleRequest() {
+  this.contextStorage.setContextId('abc-123');
+  await this.serviceA.process(); // Can read correlationId
+  await this.serviceB.process(); // Can read correlationId
+}
+```
+
+#### Context Boundaries - Where Correlation ID is Lost
+
+Correlation ID is **lost** when crossing async boundaries:
+
+```typescript
+// ❌ Lost: Event emitter
+this.contextStorage.setContextId('abc-123');
+eventEmitter.on('event', () => {
+  this.logger.info('Log'); // correlationId: undefined
+});
+
+// ❌ Lost: setTimeout/setInterval
+this.contextStorage.setContextId('abc-123');
+setTimeout(() => {
+  this.logger.info('Log'); // correlationId: undefined
+}, 100);
+
+// ❌ Lost: Manual promise without context preservation
+this.contextStorage.setContextId('abc-123');
+new Promise((resolve) => {
+  setTimeout(resolve, 100);
+}).then(() => {
+  this.logger.info('Log'); // correlationId: undefined
+});
+```
+
+#### Solutions for Context Boundaries
+
+**1. Event Emitters - Re-set correlationId:**
+
+```typescript
+// ✅ Solution: Set correlationId in event handler
+eventEmitter.on('event', async (data) => {
+  this.contextStorage.setContextId(data.correlationId);
+  this.logger.info('Processing event'); // correlationId available
+});
+```
+
+**2. Timers - Wrap in CLS.run():**
+
+```typescript
+import { ClsService } from 'nestjs-cls';
+
+// ✅ Solution: Use CLS.run() for timers
+const correlationId = this.contextStorage.getContextId();
+setTimeout(() => {
+  this.clsService.run(async () => {
+    this.clsService.set('CLS_ID', correlationId);
+    this.logger.info('Log'); // correlationId available
+  });
+}, 100);
+```
+
+**3. Worker Threads - Manual Propagation:**
+
+```typescript
+// ✅ Solution: Pass correlationId explicitly to workers
+const correlationId = this.contextStorage.getContextId();
+worker.postMessage({ correlationId, data: ... });
+
+worker.on('message', (msg) => {
+  this.contextStorage.setContextId(msg.correlationId);
+  this.logger.info('Processing'); // correlationId available
+});
+```
+
+**4. Queues and Background Jobs - Always Re-set:**
+
+```typescript
+// ✅ Solution: Extract and set at job start
+@Process('job')
+async handleJob(job: Job) {
+  // Always set correlationId at job start
+  const correlationId = job.data.correlationId || job.id.toString();
+  this.contextStorage.setContextId(correlationId);
+  
+  this.logger.info('Job started'); // correlationId available
+}
+```
+
+#### CLS Failure Handling
+
+The logger handles CLS failures gracefully:
+
+```typescript
+// If getContextId() throws, logger continues with undefined
+try {
+  const id = this.contextStorage.getContextId(); // May throw
+} catch (error) {
+  // LoggerService.getLogData() catches this
+  // Falls back to undefined correlationId
+}
+
+this.logger.info('Log'); // Never throws, correlationId: undefined if CLS fails
+```
+
+### Correlation ID Format Validation
+
+The library does **not** validate correlation ID format. Applications should validate format before setting.
+
+#### Recommended Format
+
+**Standard UUID v4** (recommended for most cases):
+
+```typescript
+import { v4 as uuidv4, validate as uuidValidate } from 'uuid';
+
+// ✅ Validate before setting
+const correlationId = req.headers['x-correlation-id'] || uuidv4();
+if (uuidValidate(correlationId)) {
+  this.contextStorage.setContextId(correlationId);
+} else {
+  // Generate new one or use fallback
+  this.contextStorage.setContextId(uuidv4());
+}
+```
+
+**Custom Format Validation:**
+
+```typescript
+// Example: Custom format (prefix + timestamp + random)
+const CORRELATION_ID_PATTERN = /^req-[0-9]{13}-[a-z0-9]{8}$/;
+
+function validateCorrelationId(id: string): boolean {
+  return CORRELATION_ID_PATTERN.test(id);
+}
+
+// ✅ Validate before setting
+const correlationId = message.correlationId;
+if (correlationId && validateCorrelationId(correlationId)) {
+  this.contextStorage.setContextId(correlationId);
+} else {
+  // Generate new one with custom format
+  const newId = `req-${Date.now()}-${Math.random().toString(36).substr(2, 8)}`;
+  this.contextStorage.setContextId(newId);
+}
+```
+
+#### Format Guidelines
+
+**Recommended:**
+- ✅ UUID v4: `550e8400-e29b-41d4-a716-446655440000`
+- ✅ Alphanumeric: `req-abc123def456`
+- ✅ With timestamp: `req-1640000000000-abc123`
+
+**Avoid:**
+- ❌ Empty strings: `""`
+- ❌ Very long strings: > 255 characters
+- ❌ Special characters that break systems: `null`, `undefined` as string
+- ❌ Newlines or control characters
+
+#### Validation in HTTP Middleware
+
+```typescript
+import { v4 as uuidv4, validate as uuidValidate } from 'uuid';
+
+ClsModule.forRoot({
+  middleware: {
+    mount: true,
+    generateId: true,
+    idGenerator: (req: Request) => {
+      const headerId = req.headers['x-correlation-id'] as string;
+      
+      // Validate format
+      if (headerId && uuidValidate(headerId)) {
+        return headerId;
+      }
+      
+      // Generate new one if invalid
+      return uuidv4();
+    },
+  },
+})
+```
+
+#### Validation in Kafka Consumers
+
+```typescript
+@KafkaListener('order.created')
+async handleOrderCreated(message: OrderCreatedEvent) {
+  // Validate before setting
+  let correlationId = message.correlationId;
+  
+  if (!correlationId || !uuidValidate(correlationId)) {
+    // Use message ID as fallback or generate new
+    correlationId = message.id || uuidv4();
+  }
+  
+  this.contextStorage.setContextId(correlationId);
+  this.logger.info('Processing order');
+}
+```
+
+---
+
+## Complete Integration Examples
+
+### HTTP Entry Point - Controller with Middleware
+
+**app.module.ts:**
+
+```typescript
+import { Module, MiddlewareConsumer, NestModule } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { ClsModule } from 'nestjs-cls';
+import { v4 as uuidv4, validate as uuidValidate } from 'uuid';
+import { ContextModule, LoggerModule } from '@infineit/winston-logger';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true }),
+    ClsModule.forRoot({
+      middleware: {
+        mount: true,
+        generateId: true,
+        idGenerator: (req: Request) => {
+          const headerId = req.headers['x-correlation-id'] as string;
+          return (headerId && uuidValidate(headerId)) ? headerId : uuidv4();
+        },
+      },
+    }),
+    ContextModule,
+    LoggerModule.forRoot({
+      nodeEnv: process.env.NODE_ENV,
+      organization: 'sales',
+      context: 'api',
+      app: 'gateway',
+    }),
+  ],
+})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    // Additional middleware can be added here
+    // ClsModule middleware is already mounted above
+  }
+}
+```
+
+**sales.controller.ts:**
+
+```typescript
+import { Controller, Get, Post, Body, Param } from '@nestjs/common';
+import { LoggerService, ContextStorageService } from '@infineit/winston-logger';
+import { KafkaProducer } from './kafka-producer';
+
+@Controller('sales')
+export class SalesController {
+  constructor(
+    private readonly logger: LoggerService,
+    private readonly contextStorage: ContextStorageService,
+    private readonly kafkaProducer: KafkaProducer,
+  ) {}
+
+  @Post('orders')
+  async createOrder(@Body() orderData: CreateOrderDto) {
+    // Correlation ID automatically available from CLS (set by middleware)
+    this.logger.info('Creating order', {
+      props: { userId: orderData.userId, amount: orderData.amount },
+    });
+
+    try {
+      const order = await this.orderService.create(orderData);
+      
+      // Extract correlationId from CLS before publishing to Kafka
+      const correlationId = this.contextStorage.getContextId();
+      
+      // Publish to Kafka with correlationId
+      await this.kafkaProducer.send({
+        topic: 'order.created',
+        messages: [{
+          key: order.id,
+          value: JSON.stringify({
+            ...order,
+            correlationId, // Propagate correlationId
+          }),
+        }],
+      });
+
+      this.logger.info('Order created and published', {
+        props: { orderId: order.id },
+      });
+
+      return order;
+    } catch (error) {
+      this.logger.error(error, {
+        props: { userId: orderData.userId },
+      });
+      throw error;
+    }
+  }
+}
+```
+
+### Kafka Producer - Propagating Correlation ID
+
+**kafka-producer.service.ts:**
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { LoggerService, ContextStorageService } from '@infineit/winston-logger';
+import { Kafka } from 'kafkajs';
+
+@Injectable()
+export class KafkaProducer {
+  constructor(
+    private readonly kafka: Kafka,
+    private readonly logger: LoggerService,
+    private readonly contextStorage: ContextStorageService,
+  ) {}
+
+  async send(topic: string, messages: Array<{ key?: string; value: string }>) {
+    // Get current correlationId from CLS
+    const correlationId = this.contextStorage.getContextId();
+    
+    // Add correlationId to message headers
+    const enrichedMessages = messages.map(msg => ({
+      ...msg,
+      headers: {
+        'x-correlation-id': correlationId || 'no-correlation-id',
+      },
+    }));
+
+    try {
+      await this.kafka.producer().send({
+        topic,
+        messages: enrichedMessages,
+      });
+      
+      this.logger.info('Message published to Kafka', {
+        props: { topic, messageCount: messages.length, correlationId },
+      });
+    } catch (error) {
+      this.logger.error(error, {
+        props: { topic, correlationId },
+      });
+      throw error;
+    }
+  }
+}
+```
+
+### Kafka Consumer - Extracting and Setting Correlation ID
+
+**order.consumer.ts:**
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { KafkaListener } from '@nestjs/microservices';
+import { LoggerService, ContextStorageService } from '@infineit/winston-logger';
+import { validate as uuidValidate } from 'uuid';
+import { v4 as uuidv4 } from 'uuid';
+
+@Injectable()
+export class OrderConsumer {
+  constructor(
+    private readonly logger: LoggerService,
+    private readonly contextStorage: ContextStorageService,
+  ) {}
+
+  @KafkaListener('order.created')
+  async handleOrderCreated(message: OrderCreatedEvent) {
+    // Extract correlationId from message or headers
+    let correlationId = message.correlationId;
+    
+    // Fallback to message ID or generate new
+    if (!correlationId || !uuidValidate(correlationId)) {
+      correlationId = message.id || uuidv4();
+    }
+    
+    // CRITICAL: Set correlationId at the start of handler
+    this.contextStorage.setContextId(correlationId);
+    
+    this.logger.info('Order received from Kafka', {
+      props: { orderId: message.id, correlationId },
+    });
+
+    try {
+      await this.processOrder(message);
+      this.logger.info('Order processed successfully', {
+        props: { orderId: message.id },
+      });
+    } catch (error) {
+      this.logger.error(error, {
+        props: { orderId: message.id, correlationId },
+      });
+      throw error;
+    }
+  }
+}
+```
+
+### Bull/BullMQ Worker - Complete Example
+
+**email.processor.ts:**
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { Processor, Process } from '@nestjs/bull';
+import { Job } from 'bull';
+import { LoggerService, ContextStorageService } from '@infineit/winston-logger';
+
+interface EmailJob {
+  to: string;
+  subject: string;
+  body: string;
+  correlationId?: string;
+  userId: string;
+}
+
+@Processor('email')
+export class EmailProcessor {
+  constructor(
+    private readonly logger: LoggerService,
+    private readonly contextStorage: ContextStorageService,
+    private readonly emailService: EmailService,
+  ) {}
+
+  @Process('send')
+  async handleSendEmail(job: Job<EmailJob>) {
+    const start = Date.now();
+    
+    // CRITICAL: Set correlationId from job data or use job ID
+    const correlationId = job.data.correlationId || job.id.toString();
+    this.contextStorage.setContextId(correlationId);
+    
+    this.logger.info('Email job started', {
+      props: {
+        jobId: job.id,
+        to: job.data.to,
+        correlationId,
+      },
+    });
+
+    try {
+      await this.emailService.send(job.data);
+      
+      const duration = Date.now() - start;
+      this.logger.info('Email sent successfully', {
+        props: {
+          jobId: job.id,
+          durationMs: duration,
+        },
+      });
+    } catch (error) {
+      this.logger.error(error, {
+        props: {
+          jobId: job.id,
+          correlationId,
+          durationMs: Date.now() - start,
+        },
+      });
+      throw error; // Re-throw for Bull retry mechanism
+    }
+  }
+}
+```
+
+**Enqueuing jobs with correlationId:**
+
+```typescript
+@Injectable()
+export class EmailService {
+  constructor(
+    private readonly emailQueue: Queue,
+    private readonly contextStorage: ContextStorageService,
+  ) {}
+
+  async sendEmail(data: EmailData) {
+    // Get current correlationId from CLS (if in HTTP context)
+    const correlationId = this.contextStorage.getContextId();
+    
+    // Enqueue job with correlationId
+    await this.emailQueue.add('send', {
+      ...data,
+      correlationId, // Propagate correlationId to job
+    });
+  }
+}
+```
+
+### CRON / Background Jobs - Complete Example
+
+**cleanup.scheduler.ts:**
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { Cron, CronExpression } from '@nestjs/schedule';
+import { LoggerService, ContextStorageService } from '@infineit/winston-logger';
+
+@Injectable()
+export class CleanupScheduler {
+  constructor(
+    private readonly logger: LoggerService,
+    private readonly contextStorage: ContextStorageService,
+    private readonly cleanupService: CleanupService,
+  ) {}
+
+  @Cron(CronExpression.EVERY_HOUR)
+  async hourlyCleanup() {
+    // Generate unique correlationId for this job
+    const correlationId = `cleanup-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    this.contextStorage.setContextId(correlationId);
+    
+    this.logger.info('Hourly cleanup job started', {
+      props: { correlationId },
+    });
+
+    try {
+      const deleted = await this.cleanupService.deleteOldRecords();
+      
+      this.logger.info('Hourly cleanup completed', {
+        props: {
+          correlationId,
+          deletedCount: deleted,
+        },
+      });
+    } catch (error) {
+      this.logger.error(error, {
+        props: { correlationId },
+      });
+      // Don't throw - CRON jobs should fail silently to prevent crashes
+    }
+  }
+
+  @Cron(CronExpression.EVERY_DAY_AT_MIDNIGHT)
+  async dailyReport() {
+    const correlationId = `daily-report-${Date.now()}`;
+    this.contextStorage.setContextId(correlationId);
+    
+    this.logger.info('Daily report generation started', {
+      props: { correlationId },
+    });
+
+    try {
+      await this.reportService.generateDailyReport();
+      this.logger.info('Daily report generated', {
+        props: { correlationId },
+      });
+    } catch (error) {
+      this.logger.error(error, {
+        props: { correlationId },
+      });
+    }
+  }
+}
+```
+
+### End-to-End Correlation ID Flow Example
+
+**Scenario: Sales → Kafka → Document → HTTP → Common Service**
+
+**1. HTTP Entry (Sales Service):**
+
+```typescript
+// sales.controller.ts
+export class SalesController {
+  constructor(
+    private readonly logger: LoggerService,
+    private readonly contextStorage: ContextStorageService,
+    private readonly kafkaProducer: KafkaProducer,
+  ) {}
+
+  @Post('orders')
+  async createOrder(@Body() orderData: CreateOrderDto) {
+    // Correlation ID set by ClsModule middleware from HTTP header
+    // Header: x-correlation-id: abc-123-def-456
+    
+    this.logger.info('Order creation request received', {
+      props: { userId: orderData.userId },
+    });
+    // Log: { correlationId: 'abc-123-def-456', ... }
+
+    const order = await this.orderService.create(orderData);
+    
+    // Extract correlationId from CLS before Kafka publish
+    const correlationId = this.contextStorage.getContextId(); // 'abc-123-def-456'
+  
+  // Publish to Kafka with correlationId
+  await this.kafkaProducer.send({
+    topic: 'order.created',
+    messages: [{
+      value: JSON.stringify({
+        ...order,
+        correlationId, // Propagate: 'abc-123-def-456'
+      }),
+    }],
+  });
+
+  return order;
+}
+```
+
+**2. Kafka Consumer (Document Service):**
+
+```typescript
+// document.consumer.ts
+@KafkaListener('order.created')
+async handleOrderCreated(message: OrderCreatedEvent) {
+  // Extract correlationId from message
+  const correlationId = message.correlationId; // 'abc-123-def-456'
+  
+  // CRITICAL: Set in CLS at handler start
+  this.contextStorage.setContextId(correlationId);
+  
+  this.logger.info('Processing order document', {
+    props: { orderId: message.id },
+  });
+  // Log: { correlationId: 'abc-123-def-456', ... }
+
+  try {
+    await this.documentService.createInvoice(message);
+    
+    // Make HTTP call to Common Service with correlationId
+    await this.httpClient.post('http://common-service/invoices', {
+      orderId: message.id,
+      correlationId, // Propagate: 'abc-123-def-456'
+    }, {
+      headers: {
+        'x-correlation-id': correlationId, // Propagate in header
+      },
+    });
+  } catch (error) {
+    this.logger.error(error, {
+      props: { orderId: message.id },
+    });
+  }
+}
+```
+
+**3. HTTP Handler (Common Service):**
+
+```typescript
+// common.controller.ts
+@Post('invoices')
+async createInvoice(@Body() data: CreateInvoiceDto, @Headers() headers: Headers) {
+  // ClsModule middleware extracts correlationId from header
+  // Header: x-correlation-id: abc-123-def-456
+  
+  this.logger.info('Invoice creation request received', {
+    props: { orderId: data.orderId },
+  });
+  // Log: { correlationId: 'abc-123-def-456', ... }
+
+  const invoice = await this.invoiceService.create(data);
+  
+  this.logger.info('Invoice created', {
+    props: { invoiceId: invoice.id, orderId: data.orderId },
+  });
+  // Log: { correlationId: 'abc-123-def-456', ... }
+
+  return invoice;
+}
+```
+
+**4. Common Service (app.module.ts):**
+
+```typescript
+@Module({
+  imports: [
+    ClsModule.forRoot({
+      middleware: {
+        mount: true,
+        generateId: true,
+        idGenerator: (req: Request) => {
+          // Extract from header (propagated from Document Service)
+          return req.headers['x-correlation-id'] as string || uuidv4();
+        },
+      },
+    }),
+    ContextModule,
+    LoggerModule.forRoot(),
+  ],
+})
+export class AppModule {}
+```
+
+**Flow Summary:**
+
+```
+HTTP Request → Sales Service
+  Header: x-correlation-id: abc-123-def-456
+  CLS: abc-123-def-456
+  Log: { correlationId: 'abc-123-def-456' }
+
+  ↓ Kafka Message
+
+Kafka Topic: order.created
+  Payload: { ..., correlationId: 'abc-123-def-456' }
+
+  ↓ Consumer
+
+Document Service
+  CLS: abc-123-def-456 (set at handler start)
+  Log: { correlationId: 'abc-123-def-456' }
+
+  ↓ HTTP Request
+
+HTTP Request → Common Service
+  Header: x-correlation-id: abc-123-def-456
+  CLS: abc-123-def-456 (extracted by middleware)
+  Log: { correlationId: 'abc-123-def-456' }
+```
+
+**Key Points:**
+
+1. ✅ **HTTP → Kafka**: Extract from CLS, include in message payload
+2. ✅ **Kafka → Consumer**: Extract from message, set in CLS at handler start
+3. ✅ **Consumer → HTTP**: Extract from CLS, include in HTTP header
+4. ✅ **HTTP → Service**: CLS middleware extracts from header automatically
+5. ✅ **All logs**: Same correlationId throughout the flow
+
 ---
 
 ## API Reference