@infineit/winston-logger 1.0.31 → 1.0.33

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)
@@ -44,6 +49,27 @@ This package requires the following peer dependencies (usually already installed
 - `@nestjs/config` 4.2.0
 - `@nestjs/core` 11.1.9
 - `nestjs-cls` 5.0.1
+- `uuid` (required for correlation ID generation in HTTP contexts)
+
+### ⚠️ Critical Setup Requirement
+
+**IMPORTANT:** `ClsModule.forRoot()` **MUST** be imported in your `AppModule` **BEFORE** `ContextModule`. This is required to avoid dependency resolution errors with `HttpAdapterHost`.
+
+**Correct import order:**
+```typescript
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true }),
+    ClsModule.forRoot({ ... }),  // ✅ FIRST - Required
+    ContextModule,                // ✅ THEN - Uses existing ClsModule
+    LoggerModule.forRoot(),       // ✅ THEN - Configures logger
+  ],
+})
+```
+
+**❌ Incorrect:** Importing `ContextModule` before `ClsModule` will cause `HttpAdapterHost` dependency errors.
+
+**Note:** `ContextModule` does NOT import `ClsModule` internally. Applications must configure `ClsModule.forRoot()` themselves.
 
 ---
 
@@ -54,12 +80,26 @@ This package requires the following peer dependencies (usually already installed
 ```typescript
 import { Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
+import { ClsModule } from 'nestjs-cls';  // REQUIRED: Must import ClsModule first
+import { v4 as uuidv4 } from 'uuid';      // REQUIRED: For correlation ID generation
 import { ContextModule, LoggerModule } from '@infineit/winston-logger';
 
 @Module({
   imports: [
     ConfigModule.forRoot({ isGlobal: true }),
-    ContextModule,  // Required for CLS (correlation ID support)
+    
+    // ⚠️ CRITICAL: ClsModule MUST be imported BEFORE ContextModule
+    ClsModule.forRoot({
+      global: true,
+      middleware: {
+        mount: true,  // Enable middleware for HTTP requests
+        generateId: true,  // Auto-generate correlation ID
+        idGenerator: (req: Request) => 
+          (req.headers['x-correlation-id'] as string) || uuidv4(),
+      },
+    }),
+    
+    ContextModule,  // Required for CLS (correlation ID support) - uses existing ClsModule
     LoggerModule.forRoot(),  // Configure logger
   ],
 })
@@ -169,10 +209,29 @@ 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')
 };
 
+import { ClsModule } from 'nestjs-cls';
+import { v4 as uuidv4 } from 'uuid';
+
 @Module({
   imports: [
+    // ⚠️ CRITICAL: ClsModule MUST be imported BEFORE ContextModule
+    ClsModule.forRoot({
+      global: true,
+      middleware: {
+        mount: true,
+        generateId: true,
+        idGenerator: (req: Request) => 
+          (req.headers['x-correlation-id'] as string) || uuidv4(),
+      },
+    }),
+    ContextModule,  // Uses existing ClsModule
     LoggerModule.forRoot(config),
   ],
 })
@@ -192,6 +251,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,16 +273,35 @@ 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,
 }));
 ```
 
 ```typescript
+import { ClsModule } from 'nestjs-cls';
+import { v4 as uuidv4 } from 'uuid';
+
 @Module({
   imports: [
     ConfigModule.forRoot({
       isGlobal: true,
       load: [loggerConfig],
     }),
+    // ⚠️ CRITICAL: ClsModule MUST be imported BEFORE ContextModule
+    ClsModule.forRoot({
+      global: true,
+      middleware: {
+        mount: true,
+        generateId: true,
+        idGenerator: (req: Request) => 
+          (req.headers['x-correlation-id'] as string) || uuidv4(),
+      },
+    }),
+    ContextModule,  // Uses existing ClsModule configuration
     LoggerModule.forRoot(),  // Will read from ConfigService
   ],
 })
@@ -233,12 +319,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
+```
 
 ---
 
@@ -271,21 +397,26 @@ export class UserController {
 }
 ```
 
-**Important**: For HTTP services, you must configure CLS middleware manually:
+**Important**: For HTTP services, you must configure CLS middleware manually. **ClsModule MUST be imported BEFORE ContextModule:**
 
 ```typescript
 import { ClsModule } from 'nestjs-cls';
+import { v4 as uuidv4 } from 'uuid';
+import { ContextModule, LoggerModule } from '@infineit/winston-logger';
 
 @Module({
   imports: [
+    // ⚠️ CRITICAL: ClsModule MUST be imported FIRST
     ClsModule.forRoot({
+      global: true,
       middleware: {
         mount: true,  // Enable middleware
         generateId: true,  // Auto-generate correlation ID
-        idGenerator: (req: Request) => req.headers['x-correlation-id'] || uuidv4(),
+        idGenerator: (req: Request) => 
+          (req.headers['x-correlation-id'] as string) || uuidv4(),
       },
     }),
-    ContextModule,  // Provides CLS service
+    ContextModule,  // Provides CLS service - uses existing ClsModule
     LoggerModule.forRoot(),
   ],
 })
@@ -478,8 +609,10 @@ export class KafkaTransport implements LoggerTransport {
 ### Registering Custom Transports
 
 ```typescript
-import { Provider } from '@nestjs/common';
-import { LoggerModule } from '@infineit/winston-logger';
+import { Provider, Module } from '@nestjs/common';
+import { ClsModule } from 'nestjs-cls';
+import { v4 as uuidv4 } from 'uuid';
+import { ContextModule, LoggerModule } from '@infineit/winston-logger';
 import { KafkaTransport } from './kafka-transport';
 
 const customTransports: Provider[] = [
@@ -491,6 +624,17 @@ const customTransports: Provider[] = [
 
 @Module({
   imports: [
+    // ⚠️ CRITICAL: ClsModule MUST be imported BEFORE ContextModule
+    ClsModule.forRoot({
+      global: true,
+      middleware: {
+        mount: true,
+        generateId: true,
+        idGenerator: (req: Request) => 
+          (req.headers['x-correlation-id'] as string) || uuidv4(),
+      },
+    }),
+    ContextModule,  // Uses existing ClsModule
     LoggerModule.forRoot(config, customTransports),
   ],
 })
@@ -509,6 +653,210 @@ 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
+import { ClsModule } from 'nestjs-cls';
+import { v4 as uuidv4 } from 'uuid';
+import { ContextModule, LoggerModule } from '@infineit/winston-logger';
+
+@Module({
+  imports: [
+    // ⚠️ CRITICAL: ClsModule MUST be imported BEFORE ContextModule
+    ClsModule.forRoot({
+      global: true,
+      middleware: {
+        mount: true,
+        generateId: true,
+        idGenerator: (req: Request) => 
+          (req.headers['x-correlation-id'] as string) || uuidv4(),
+      },
+    }),
+    ContextModule,  // Uses existing ClsModule
+    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
@@ -624,159 +972,913 @@ Correlation ID is **optional** - `undefined` is valid:
 
 ### HTTP Context Setup
 
-For HTTP services, configure CLS middleware:
+For HTTP services, configure CLS middleware. **ClsModule MUST be imported BEFORE ContextModule:**
 
 ```typescript
 import { ClsModule } from 'nestjs-cls';
 import { v4 as uuidv4 } from 'uuid';
+import { ContextModule, LoggerModule } from '@infineit/winston-logger';
 
 @Module({
   imports: [
+    // ⚠️ CRITICAL: ClsModule MUST be imported FIRST
     ClsModule.forRoot({
+      global: true,
       middleware: {
         mount: true,
         generateId: true,
         idGenerator: (req: Request) => {
           // Use existing correlation ID from header, or generate new one
-          return req.headers['x-correlation-id'] as string || uuidv4();
+          return (req.headers['x-correlation-id'] as string) || uuidv4();
         },
       },
     }),
-    ContextModule,  // Provides CLS service
+    ContextModule,  // Uses existing ClsModule configuration
     LoggerModule.forRoot(),
   ],
 })
 export class AppModule {}
 ```
 
----
-
-## API Reference
+**Important:** The import order is critical. `ClsModule.forRoot()` must be imported before `ContextModule` to avoid `HttpAdapterHost` dependency resolution errors.
 
-### LoggerService
+### CLS Context Boundaries and Edge Cases
 
-Main logging service injected into your classes.
+#### Async Context Propagation
 
-#### Methods
+CLS (AsyncLocalStorage) automatically propagates correlation ID within the same async context chain:
 
 ```typescript
-// Generic log method
-log(level: LogLevel, message: string | Error, data?: LogData, profile?: string): void
-
-// Convenience methods
-debug(message: string, data?: LogData, profile?: string): void
-info(message: string, data?: LogData, profile?: string): void
-warn(message: string | Error, data?: LogData, profile?: string): void
-error(message: string | Error, data?: LogData, profile?: string): void
-fatal(message: string | Error, data?: LogData, profile?: string): void
-emergency(message: string | Error, data?: LogData, profile?: string): void
-
-// Profile (currently not implemented in transport architecture)
-startProfile(id: string): void
+// ✅ 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
+}
 ```
 
-#### LogLevel
+#### Context Boundaries - Where Correlation ID is Lost
+
+Correlation ID is **lost** when crossing async boundaries:
 
 ```typescript
-enum LogLevel {
-  Emergency = 'emergency',  // One or more systems are unusable
-  Fatal = 'fatal',          // A person must take an action immediately
-  Error = 'error',         // Error events are likely to cause problems
-  Warn = 'warn',           // Warning events might cause problems
-  Info = 'info',          // Routine information
-  Debug = 'debug',        // Debug or trace information
-}
+// ❌ 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
+});
 ```
 
-#### LogData
+#### Solutions for Context Boundaries
+
+**1. Event Emitters - Re-set correlationId:**
 
 ```typescript
-interface LogData {
-  organization?: string;      // Override config organization
-  context?: string;          // Override config context
-  app?: string;             // Override config app
-  sourceClass?: string;     // Override auto-detected class name
-  correlationId?: string;   // Override CLS correlation ID
-  error?: SerializedError; // Error (must be serialized)
-  props?: Record<string, any>; // Custom properties
-  durationMs?: number;      // Duration in milliseconds
-}
+// ✅ Solution: Set correlationId in event handler
+eventEmitter.on('event', async (data) => {
+  this.contextStorage.setContextId(data.correlationId);
+  this.logger.info('Processing event'); // correlationId available
+});
 ```
 
-### ContextStorageService
-
-Service for managing CLS context (correlation ID).
-
-#### Methods
+**2. Timers - Wrap in CLS.run():**
 
 ```typescript
-// Get correlation ID from CLS
-getContextId(): string | undefined
+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);
+```
 
-// Set correlation ID in CLS
-setContextId(id: string): void
+**3. Worker Threads - Manual Propagation:**
 
-// Get any value from CLS
-get<T>(key: string): T | undefined
+```typescript
+// ✅ Solution: Pass correlationId explicitly to workers
+const correlationId = this.contextStorage.getContextId();
+worker.postMessage({ correlationId, data: ... });
 
-// Set any value in CLS
-set<T>(key: string, value: T): void
+worker.on('message', (msg) => {
+  this.contextStorage.setContextId(msg.correlationId);
+  this.logger.info('Processing'); // correlationId available
+});
 ```
 
----
+**4. Queues and Background Jobs - Always Re-set:**
 
-## Migration Guide (Legacy app.useLogger Users)
+```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
+}
+```
 
-### ⚠️ Deprecated: app.useLogger() and app.flushLogs()
+#### CLS Failure Handling
 
-If you're migrating from an older version of `@infineit/winston-logger` that used `app.useLogger()` and `app.flushLogs()`, this section is for you.
+The logger handles CLS failures gracefully:
 
-**Status**: These methods have been **removed** and are **no longer available**.
+```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
+}
 
-### Why Was It Removed?
+this.logger.info('Log'); // Never throws, correlationId: undefined if CLS fails
+```
 
-The `app.useLogger()` and `app.flushLogs()` methods were removed for the following architectural reasons:
+### Correlation ID Format Validation
 
-1. **HTTP Assumption Violation**: These methods assumed HTTP runtime, making the logger unusable in Kafka consumers, Bull workers, CRON jobs, and CLI tasks.
+The library does **not** validate correlation ID format. Applications should validate format before setting.
 
-2. **Middleware Auto-Mounting**: The old pattern auto-mounted middleware, violating the library's core principle that applications must configure middleware themselves.
+#### Recommended Format
 
-3. **Transport Architecture**: The new architecture uses a pluggable `LoggerTransport[]` system where Winston is one transport among many, not the only transport.
+**Standard UUID v4** (recommended for most cases):
 
-4. **Fire-and-Forget Guarantee**: The new architecture ensures all logging is truly fire-and-forget without requiring explicit `flushLogs()` calls.
+```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());
+}
+```
 
-### Old Deprecated Usage ❌
+**Custom Format Validation:**
 
 ```typescript
-// ❌ DEPRECATED - This no longer works
-import { NestFactory } from '@nestjs/core';
-import { LoggerModule } from '@infineit/winston-logger';
+// Example: Custom format (prefix + timestamp + random)
+const CORRELATION_ID_PATTERN = /^req-[0-9]{13}-[a-z0-9]{8}$/;
 
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  
-  // ❌ DEPRECATED: app.useLogger() is removed
-  app.useLogger(app.get(LoggerModule));
-  
-  await app.listen(3000);
-  
-  // ❌ DEPRECATED: app.flushLogs() is removed
-  app.flushLogs();
+function validateCorrelationId(id: string): boolean {
+  return CORRELATION_ID_PATTERN.test(id);
 }
 
-bootstrap();
+// ✅ 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);
+}
 ```
 
-### New Correct Usage ✅
+#### Format Guidelines
 
-```typescript
-// ✅ CORRECT: Use LoggerService injection
+**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 { ClsModule } from 'nestjs-cls';
+import { v4 as uuidv4, validate as uuidValidate } from 'uuid';
+
+// ⚠️ CRITICAL: ClsModule MUST be imported BEFORE ContextModule in AppModule
+ClsModule.forRoot({
+  global: true,
+  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 }),
+    // ⚠️ CRITICAL: ClsModule MUST be imported FIRST
+    ClsModule.forRoot({
+      global: true,
+      middleware: {
+        mount: true,
+        generateId: true,
+        idGenerator: (req: Request) => {
+          const headerId = req.headers['x-correlation-id'] as string;
+          return (headerId && uuidValidate(headerId)) ? headerId : uuidv4();
+        },
+      },
+    }),
+    ContextModule,  // Uses existing ClsModule configuration
+    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
+import { ClsModule } from 'nestjs-cls';
+import { v4 as uuidv4 } from 'uuid';
+import { ContextModule, LoggerModule } from '@infineit/winston-logger';
+
+@Module({
+  imports: [
+    // ⚠️ CRITICAL: ClsModule MUST be imported FIRST
+    ClsModule.forRoot({
+      global: true,
+      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,  // Uses existing ClsModule configuration
+    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
+
+### LoggerService
+
+Main logging service injected into your classes.
+
+#### Methods
+
+```typescript
+// Generic log method
+log(level: LogLevel, message: string | Error, data?: LogData, profile?: string): void
+
+// Convenience methods
+debug(message: string, data?: LogData, profile?: string): void
+info(message: string, data?: LogData, profile?: string): void
+warn(message: string | Error, data?: LogData, profile?: string): void
+error(message: string | Error, data?: LogData, profile?: string): void
+fatal(message: string | Error, data?: LogData, profile?: string): void
+emergency(message: string | Error, data?: LogData, profile?: string): void
+
+// Profile (currently not implemented in transport architecture)
+startProfile(id: string): void
+```
+
+#### LogLevel
+
+```typescript
+enum LogLevel {
+  Emergency = 'emergency',  // One or more systems are unusable
+  Fatal = 'fatal',          // A person must take an action immediately
+  Error = 'error',         // Error events are likely to cause problems
+  Warn = 'warn',           // Warning events might cause problems
+  Info = 'info',          // Routine information
+  Debug = 'debug',        // Debug or trace information
+}
+```
+
+#### LogData
+
+```typescript
+interface LogData {
+  organization?: string;      // Override config organization
+  context?: string;          // Override config context
+  app?: string;             // Override config app
+  sourceClass?: string;     // Override auto-detected class name
+  correlationId?: string;   // Override CLS correlation ID
+  error?: SerializedError; // Error (must be serialized)
+  props?: Record<string, any>; // Custom properties
+  durationMs?: number;      // Duration in milliseconds
+}
+```
+
+### ContextStorageService
+
+Service for managing CLS context (correlation ID).
+
+#### Methods
+
+```typescript
+// Get correlation ID from CLS
+getContextId(): string | undefined
+
+// Set correlation ID in CLS
+setContextId(id: string): void
+
+// Get any value from CLS
+get<T>(key: string): T | undefined
+
+// Set any value in CLS
+set<T>(key: string, value: T): void
+```
+
+---
+
+## Migration Guide (Legacy app.useLogger Users)
+
+### ⚠️ Deprecated: app.useLogger() and app.flushLogs()
+
+If you're migrating from an older version of `@infineit/winston-logger` that used `app.useLogger()` and `app.flushLogs()`, this section is for you.
+
+**Status**: These methods have been **removed** and are **no longer available**.
+
+### Why Was It Removed?
+
+The `app.useLogger()` and `app.flushLogs()` methods were removed for the following architectural reasons:
+
+1. **HTTP Assumption Violation**: These methods assumed HTTP runtime, making the logger unusable in Kafka consumers, Bull workers, CRON jobs, and CLI tasks.
+
+2. **Middleware Auto-Mounting**: The old pattern auto-mounted middleware, violating the library's core principle that applications must configure middleware themselves.
+
+3. **Transport Architecture**: The new architecture uses a pluggable `LoggerTransport[]` system where Winston is one transport among many, not the only transport.
+
+4. **Fire-and-Forget Guarantee**: The new architecture ensures all logging is truly fire-and-forget without requiring explicit `flushLogs()` calls.
+
+### Old Deprecated Usage ❌
+
+```typescript
+// ❌ DEPRECATED - This no longer works
 import { NestFactory } from '@nestjs/core';
+import { LoggerModule } from '@infineit/winston-logger';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  
+  // ❌ DEPRECATED: app.useLogger() is removed
+  app.useLogger(app.get(LoggerModule));
+  
+  await app.listen(3000);
+  
+  // ❌ DEPRECATED: app.flushLogs() is removed
+  app.flushLogs();
+}
+
+bootstrap();
+```
+
+### New Correct Usage ✅
+
+```typescript
+// ✅ CORRECT: Use LoggerService injection
+import { NestFactory } from '@nestjs/core';
+import { ClsModule } from 'nestjs-cls';
+import { v4 as uuidv4 } from 'uuid';
 import { ContextModule, LoggerModule } from '@infineit/winston-logger';
 
 @Module({
   imports: [
-    ContextModule,
+    // ⚠️ CRITICAL: ClsModule MUST be imported BEFORE ContextModule
+    ClsModule.forRoot({
+      global: true,
+      middleware: {
+        mount: true,
+        generateId: true,
+        idGenerator: (req: Request) => 
+          (req.headers['x-correlation-id'] as string) || uuidv4(),
+      },
+    }),
+    ContextModule,  // Uses existing ClsModule
     LoggerModule.forRoot(),
   ],
 })
@@ -935,14 +2037,22 @@ async function bootstrap() {
 ```typescript
 import { NestFactory } from '@nestjs/core';
 import { ClsModule } from 'nestjs-cls';
+import { v4 as uuidv4 } from 'uuid';
 import { ContextModule, LoggerModule } from '@infineit/winston-logger';
 
 @Module({
   imports: [
+    // ⚠️ CRITICAL: ClsModule MUST be imported FIRST
     ClsModule.forRoot({
-      middleware: { mount: true, generateId: true },
+      global: true,
+      middleware: { 
+        mount: true, 
+        generateId: true,
+        idGenerator: (req: Request) => 
+          (req.headers['x-correlation-id'] as string) || uuidv4(),
+      },
     }),
-    ContextModule,  // ✅ Add
+    ContextModule,  // ✅ Uses existing ClsModule
     LoggerModule.forRoot(),  // ✅ Add
   ],
 })
@@ -960,10 +2070,11 @@ async function bootstrap() {
 
 If you encounter issues during migration:
 
-1. **Check module imports**: Ensure `ContextModule` and `LoggerModule.forRoot()` are in your `AppModule`
-2. **Check CLS setup**: For HTTP services, ensure `ClsModule` is configured
-3. **Check injection**: Ensure `LoggerService` is injected via constructor
-4. **Review examples**: See the "Usage in Different Contexts" section above
+1. **Check module imports**: Ensure `ClsModule.forRoot()` is imported **BEFORE** `ContextModule`, then `LoggerModule.forRoot()` in your `AppModule`
+2. **Check CLS setup**: For HTTP services, ensure `ClsModule.forRoot()` is configured with `middleware: { mount: true, generateId: true }`
+3. **Check import order**: `ClsModule` must come before `ContextModule` to avoid `HttpAdapterHost` dependency errors
+4. **Check injection**: Ensure `LoggerService` is injected via constructor
+5. **Review examples**: See the "Usage in Different Contexts" section above
 
 ---
 
@@ -1131,15 +2242,17 @@ import { ContextModule, LoggerModule } from '@infineit/winston-logger';
 @Module({
   imports: [
     ConfigModule.forRoot({ isGlobal: true }),
+    // ⚠️ CRITICAL: ClsModule MUST be imported FIRST
     ClsModule.forRoot({
+      global: true,
       middleware: {
         mount: true,
         generateId: true,
         idGenerator: (req: Request) => 
-          req.headers['x-correlation-id'] as string || uuidv4(),
+          (req.headers['x-correlation-id'] as string) || uuidv4(),
       },
     }),
-    ContextModule,
+    ContextModule,  // Uses existing ClsModule configuration
     LoggerModule.forRoot({
       nodeEnv: process.env.NODE_ENV,
       organization: 'my-org',
@@ -1149,7 +2262,6 @@ import { ContextModule, LoggerModule } from '@infineit/winston-logger';
   ],
 })
 export class AppModule {}
-```
 
 ```typescript
 import { Injectable } from '@nestjs/common';