@infineit/winston-logger 1.0.30 → 1.0.32

package/README.md

@@ -1,169 +1,2261 @@
-<br />
-<div align="center">
-<h3 align="center">NestJS Logger</h3>
+# @infineit/winston-logger
 
-  <p align="center">
-    A Nest.js production-ready logger implementation.
-  </p>
-</div>
+Enterprise-level logging library for NestJS applications with support for multiple contexts (HTTP, Kafka, Bull/BullMQ, CRON, CLI) and flexible transport architecture.
 
+## Features
 
-## Introduction
+- ✅ **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 (HTTP forwarding uses built-in Node.js modules)
+- ✅ **Type-Safe**: Full TypeScript support with comprehensive type definitions
 
-`@infineit/winston-logger` is a lightweight project for implements a production-ready logger for Nest.js applications using Winston, Morgan and Prisma. This package simplifies the setup of logger and provides configurable options for instrumenting your application.
+## Table of Contents
 
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Architecture Overview](#architecture-overview)
+- [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)
+- [Forbidden Actions](#forbidden-actions)
+- [Examples](#examples)
 
-## Features
+---
 
-- **Easy Integration**: Quickly integrate logger with winston for distributed log.
-- **Configurable**: Provides options to customize logger configuration.
-- **Lightweight**: Minimal dependencies and overhead.
+## Installation
 
-That implements a production-ready system advanced or basic Microservices or Monoliths projects applying concepts like:
+```bash
+npm install @infineit/winston-logger
+```
 
-* Correlation IDs
-* Decoupled log transporters
-* Log levels
-* Logging Rules
-* Log formatters
+### Peer Dependencies
 
-## Installation
+This package requires the following peer dependencies (usually already installed in NestJS projects):
 
-* You can install this package using npm:
-  ```bash
-  npm install @infineit/winston-logger
-  ```
+- `@nestjs/common` 11.1.9
+- `@nestjs/config` 4.2.0
+- `@nestjs/core` 11.1.9
+- `nestjs-cls` 5.0.1
 
-  Or using Yarn:
-  ```bash
-  yarn add @infineit/winston-logger
-  ```  
+---
 
-### Prerequisites
+## Quick Start
 
-- NestJS
-- Winston
-- morgon
-- prisma
+### 1. Import Modules
 
-### Getting Started
+```typescript
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { ContextModule, LoggerModule } from '@infineit/winston-logger';
 
-Follow these steps to set up and run logger. If all steps are followed correctly, logger should start without any issues:
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true }),
+    ContextModule,  // Required for CLS (correlation ID support)
+    LoggerModule.forRoot(),  // Configure logger
+  ],
+})
+export class AppModule {}
+```
 
-1. To use `@infineit/winston-logger` in your NestJS application, simply import it of your `main.ts` file:
+### 2. Use LoggerService
 
-    ```bash
-        import { NestjsLoggerServiceAdapter } from '@infineit/winston-logger';;
+```typescript
+import { Injectable } from '@nestjs/common';
+import { LoggerService } from '@infineit/winston-logger';
 
-        const app = await NestFactory.create(AppModule, {bufferLogs: true });
+@Injectable()
+export class MyService {
+  constructor(private readonly logger: LoggerService) {}
 
-        app.useLogger(app.get(NestjsLoggerServiceAdapter));
-    ```
+  doSomething() {
+    this.logger.info('Processing started', {
+      userId: 123,
+      action: 'process',
+    });
 
-2. import in app.module.ts:
+    try {
+      // Your business logic
+    } catch (error) {
+      this.logger.error(error, {
+        userId: 123,
+        action: 'process',
+      });
+    }
+  }
+}
+```
 
-    ```bash
-      import { ContextModule, LoggerModule } from '@infineit/winston-logger';
+---
 
-      @Module({
-        imports: [
-          ContextModule,
-          LoggerModule.forRoot(PrismaService),
-        ]
-      })
-    ```
+## Architecture Overview
 
-3. app.service.ts:
+### LoggerService → LoggerTransport[] Flow
 
-    ```bash
-      import Logger, { LoggerKey } from '@infineit/winston-logger';
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Application Code                         │
+│  (HTTP Services, Kafka Consumers, Bull Workers, etc.)      │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    LoggerService                            │
+│  • Normalizes logs                                          │
+│  • Serializes errors                                        │
+│  • Retrieves correlationId from CLS                        │
+│  • Sends to all transports (fire-and-forget)               │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+         ┌───────────────────────┐
+         │  NormalizedLog        │
+         │  • timestamp          │
+         │  • level              │
+         │  • message            │
+         │  • error (serialized)│
+         │  • correlationId      │
+         │  • ...                │
+         └───────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│              LoggerTransport[] (Array)                     │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+        ┌────────────┼────────────┐
+        │            │            │
+        ▼            ▼            ▼
+┌──────────────┐ ┌──────────┐ ┌──────────┐
+│WinstonTransport│ │ Custom   │ │ Custom   │
+│   Adapter     │ │ Transport│ │ Transport│
+│               │ │          │ │          │
+│ • Console     │ │ • Kafka  │ │ • HTTP   │
+│ • File        │ │ • Database│ │ • etc.   │
+│ • Slack       │ │          │ │          │
+└──────────────┘ └──────────┘ └──────────┘
+```
 
-      constructor(@Inject(LoggerKey) private logger: Logger) {}
+### Key Components
 
-      this.logger.info('I am an info message!', {
-            props: {
-                foo: 'bar',
-                baz: 'qux',
-            },
-        });
-    ```
+1. **LoggerService**: Main logging service that normalizes logs and sends them to transports
+2. **LoggerTransport**: Interface for all log transports (Winston, Kafka, HTTP, Database, etc.)
+3. **WinstonTransportAdapter**: Wraps Winston as one transport among many
+4. **ContextModule**: Provides CLS (AsyncLocalStorage) for correlation ID management
+5. **NormalizedLog**: Standardized log format sent to all transports
 
-**Reminder**: Make sure prisma is initialize and winstonlog modal is running before starting your NestJS application to avoid initialization errors.
+---
 
 ## Configuration
 
-You can configure the Logger using environment variables in your `.env` file:
+### LoggerModule Configuration
+
+```typescript
+import { LoggerModule, LoggerModuleConfig } from '@infineit/winston-logger';
+
+const config: LoggerModuleConfig = {
+  nodeEnv: 'production',              // 'production' | 'testing' | 'development'
+  slack_webhook: 'https://...',       // Slack webhook URL (optional)
+  console_print: true,                 // Enable console output (boolean or 'true'/'false')
+  log_in_file: true,                  // Enable file logging (boolean or 'true'/'false')
+  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({
+  imports: [
+    LoggerModule.forRoot(config),
+  ],
+})
+export class AppModule {}
+```
+
+### Configuration via Environment Variables
+
+You can also configure via `@nestjs/config`:
+
+```typescript
+// .env
+NODE_ENV=production
+SLACK_WEBHOOK=https://hooks.slack.com/services/...
+CONSOLE_PRINT=true
+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
+// logger.config.ts
+import { registerAs } from '@nestjs/config';
+
+export default registerAs('logger', () => ({
+  nodeEnv: process.env.NODE_ENV,
+  slack_webhook: process.env.SLACK_WEBHOOK,
+  console_print: process.env.CONSOLE_PRINT,
+  log_in_file: process.env.LOG_IN_FILE,
+  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
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      isGlobal: true,
+      load: [loggerConfig],
+    }),
+    LoggerModule.forRoot(),  // Will read from ConfigService
+  ],
+})
+export class AppModule {}
+```
+
+### Configuration Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `nodeEnv` | `string` | No | `undefined` | Environment: `'production'`, `'testing'`, or `'development'` |
+| `slack_webhook` | `string` | No | `undefined` | Slack webhook URL for fatal error notifications |
+| `console_print` | `boolean \| string` | No | `false` | Enable console output (`true`/`false` or `'true'`/`'false'`) |
+| `log_in_file` | `boolean \| string` | No | `false` | Enable file logging (`true`/`false` or `'true'`/`'false'`) |
+| `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
+```
+
+---
+
+## Usage in Different Contexts
+
+### HTTP Services
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { LoggerService } from '@infineit/winston-logger';
+
+@Injectable()
+export class UserController {
+  constructor(private readonly logger: LoggerService) {}
+
+  @Get('/users/:id')
+  async getUser(@Param('id') id: string) {
+    // Correlation ID is automatically retrieved from CLS
+    // (if CLS middleware is configured in your app)
+    this.logger.info('Fetching user', { userId: id });
+    
+    try {
+      const user = await this.userService.findById(id);
+      return user;
+    } catch (error) {
+      this.logger.error(error, { userId: id });
+      throw error;
+    }
+  }
+}
+```
+
+**Important**: For HTTP services, you must configure CLS middleware manually:
+
+```typescript
+import { ClsModule } from 'nestjs-cls';
+
+@Module({
+  imports: [
+    ClsModule.forRoot({
+      middleware: {
+        mount: true,  // Enable middleware
+        generateId: true,  // Auto-generate correlation ID
+        idGenerator: (req: Request) => req.headers['x-correlation-id'] || uuidv4(),
+      },
+    }),
+    ContextModule,  // Provides CLS service
+    LoggerModule.forRoot(),
+  ],
+})
+export class AppModule {}
+```
+
+### Kafka Consumers
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { LoggerService } from '@infineit/winston-logger';
+import { ContextStorageService } from '@infineit/winston-logger';
+
+@Injectable()
+export class OrderConsumer {
+  constructor(
+    private readonly logger: LoggerService,
+    private readonly contextStorage: ContextStorageService,
+  ) {}
+
+  @KafkaListener('order.created')
+  async handleOrderCreated(message: OrderCreatedEvent) {
+    // Set correlation ID from Kafka message
+    this.contextStorage.setContextId(message.correlationId || message.id);
+    
+    this.logger.info('Processing order', {
+      orderId: message.id,
+      userId: message.userId,
+    });
+
+    try {
+      await this.processOrder(message);
+    } catch (error) {
+      this.logger.error(error, {
+        orderId: message.id,
+      });
+    }
+  }
+}
+```
+
+### Bull/BullMQ Workers
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { Processor, Process } from '@nestjs/bull';
+import { Job } from 'bull';
+import { LoggerService } from '@infineit/winston-logger';
+import { ContextStorageService } from '@infineit/winston-logger';
+
+@Processor('email')
+export class EmailProcessor {
+  constructor(
+    private readonly logger: LoggerService,
+    private readonly contextStorage: ContextStorageService,
+  ) {}
+
+  @Process('send')
+  async handleSendEmail(job: Job<EmailJob>) {
+    // Set correlation ID from job
+    this.contextStorage.setContextId(job.id.toString());
+    
+    this.logger.info('Sending email', {
+      jobId: job.id,
+      email: job.data.to,
+    });
+
+    try {
+      await this.emailService.send(job.data);
+      this.logger.info('Email sent', {
+        jobId: job.id,
+        durationMs: Date.now() - job.timestamp,
+      });
+    } catch (error) {
+      this.logger.error(error, {
+        jobId: job.id,
+      });
+      throw error;
+    }
+  }
+}
+```
+
+### CRON Jobs
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { Cron, CronExpression } from '@nestjs/schedule';
+import { LoggerService } from '@infineit/winston-logger';
+import { ContextStorageService } from '@infineit/winston-logger';
+
+@Injectable()
+export class CleanupService {
+  constructor(
+    private readonly logger: LoggerService,
+    private readonly contextStorage: ContextStorageService,
+  ) {}
+
+  @Cron(CronExpression.EVERY_HOUR)
+  async cleanup() {
+    // Set correlation ID for this job
+    this.contextStorage.setContextId(`cleanup-${Date.now()}`);
+    
+    this.logger.info('Starting cleanup job');
+
+    try {
+      const deleted = await this.repository.deleteOldRecords();
+      this.logger.info('Cleanup completed', {
+        deletedCount: deleted,
+      });
+    } catch (error) {
+      this.logger.error(error);
+    }
+  }
+}
+```
+
+### CLI Tasks
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { LoggerService } from '@infineit/winston-logger';
+import { ContextStorageService } from '@infineit/winston-logger';
+
+@Injectable()
+export class MigrationService {
+  constructor(
+    private readonly logger: LoggerService,
+    private readonly contextStorage: ContextStorageService,
+  ) {}
+
+  async runMigration() {
+    // Set correlation ID for this task
+    this.contextStorage.setContextId(`migration-${Date.now()}`);
+    
+    this.logger.info('Starting migration');
+
+    try {
+      await this.migrate();
+      this.logger.info('Migration completed');
+    } catch (error) {
+      this.logger.error(error);
+      process.exit(1);
+    }
+  }
+}
+```
+
+---
+
+## Transport Architecture
+
+### Built-in Transports
+
+The library includes `WinstonTransportAdapter` which wraps Winston and provides:
+
+- **ConsoleTransport**: Colorized console output
+- **FileTransport**: Daily rotating file logs (`logs/log-YYYY-MM-DD-HH.log`)
+- **SlackTransport**: Fatal error notifications to Slack
+
+### Custom Transports
+
+You can create custom transports by implementing the `LoggerTransport` interface:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { LoggerTransport, NormalizedLog } from '@infineit/winston-logger';
+
+@Injectable()
+export class KafkaTransport implements LoggerTransport {
+  constructor(private readonly kafkaProducer: KafkaProducer) {}
+
+  log(normalizedLog: NormalizedLog): void {
+    try {
+      // Send to Kafka (fire-and-forget)
+      this.kafkaProducer.send({
+        topic: 'logs',
+        messages: [{
+          value: JSON.stringify(normalizedLog),
+        }],
+      });
+    } catch (error) {
+      // Swallow errors - never break business logic
+      console.error('KafkaTransport error (swallowed):', error);
+    }
+  }
+}
+```
+
+### Registering Custom Transports
+
+```typescript
+import { Provider } from '@nestjs/common';
+import { LoggerModule } from '@infineit/winston-logger';
+import { KafkaTransport } from './kafka-transport';
+
+const customTransports: Provider[] = [
+  {
+    provide: KafkaTransport,
+    useClass: KafkaTransport,
+  },
+];
+
+@Module({
+  imports: [
+    LoggerModule.forRoot(config, customTransports),
+  ],
+})
+export class AppModule {}
+```
+
+### Transport Requirements
+
+All transports must:
+
+1. ✅ Implement `LoggerTransport` interface
+2. ✅ Accept `NormalizedLog` (never raw `Error` objects)
+3. ✅ Be fire-and-forget (non-blocking)
+4. ✅ Never throw errors
+5. ✅ Handle failures gracefully
+
+---
+
+## 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
 
-- `NODE_ENV`: development / staging / testing / production.
-- `LOGGER_ORGANIZATION`: The name of your organization as it will appear in log.
-- `LOGGER_CONTEXT`: The name of your context as it will appear in log.
-- `LOGGER_APP`: The name of your app as it will appear in log.
-- `LOGGER_DATABASE_STORAGE`: True/False. Default True for production or testing, It will store log to database.
-- `LOGGER_LOG_LEVEL`: Default log level warn,error,fatal for production or testing, It will log.
-- `LOGGER_DURATION`: True/False. Default False, It will store request duration in database.
-- `LOGGER_DURATION_LOG_LEVEL`: Default log level warn,error,fatal for production or testing, It will calculate duration for request.
-- `LOGGER_CONSOLE_PRINT`: True/False. Default False for production or testing.
-- `LOGGER_LOG_IN_FILE`: True/False. Default False for production or testing.
-- `LOGGER_SLACK_INC_WEBHOOK_URL`: Slack url, eg. `https://hooks.slack.com/services/XXXXXXXXX/XXXXXXXXX/XXXXXXXXXXXXXXXXXXXXXXXX`.
+**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
 
-## Project structure
+**No changes required:** If CLS is configured, correlationId is automatically included in forwarded logs.
 
-## Key concepts
+### Fire-and-Forget Behavior
 
-### NestJS Logger
+Central log forwarding is completely fire-and-forget:
 
-NestJS uses a custom logger for bootstrap and internal logging. To use our logger, we need to create an adapter that implements the NestJS `LoggerService` interface. That is implemented in the `NestjsLoggerServiceAdapter` class.
+- ✅ **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
 
-We pass that adapter to the NestJS app on the `main.ts` file.
+**Important:** Original logging behavior remains completely unchanged. Forwarding is an additional, optional layer that runs in parallel.
 
-### Correlation IDs
+### Environment-Specific Configuration
 
-To manage correlation IDs, we use `nestjs-cls` library that implements a Local Storage. With that, we can isolate and share data on a request lifecycle.
+**Development:**
+```bash
+# Option 1: Disable forwarding in development
+LOGGER_FORWARD_TO_CENTRAL=false
 
-The system reads the `x-correlation-id` HTTP header and stores it on the Local Storage. If the header is not present, the system generates a new UUID and stores it on the Local Storage.
+# Option 2: Use local endpoint for testing
+LOGGER_FORWARD_TO_CENTRAL=true
+LOGGER_TRANSPORT_TYPE=http
+LOGGER_HTTP_ENDPOINT=http://localhost:3000/api/logs
+```
 
-### Context Wrapper
+**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
 
-To add custom data to all the logs, we use a wrapper `LoggerContextWrapper`.
+# OR Kafka forwarding (better performance, requires Kafka producer)
+LOGGER_FORWARD_TO_CENTRAL=true
+LOGGER_TRANSPORT_TYPE=kafka
+LOGGER_KAFKA_TOPIC=project-logs-<project-name>
+```
 
-That class is injected with a Transient scope. By that, we can get the caller class and add it to the logs.
+**Project-Specific Topics (Kafka):**
+Use different Kafka topics per project for better log organization:
+```bash
+# Sales project
+LOGGER_KAFKA_TOPIC=project-logs-sales
 
-## Prisma Table
+# Document project
+LOGGER_KAFKA_TOPIC=project-logs-document
 
-  ```
-      model winstonlog {
-          id_log        String   @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
-          level         String   @db.VarChar(80)
-          message       String   @db.Text
-          context       String?  @db.VarChar(255)
-          correlationId String?  @db.Uuid
-          sourceClass   String?  @db.VarChar(255)
-          props         Json?
-          organization  String?  @db.VarChar(40)
-          app           String?  @db.VarChar(40)
-          durationMs    Decimal? @default(0) @db.Decimal(10, 4)
-          stack         String?  @db.Text
-          label         String?  @db.VarChar(40)
-          timestamp     DateTime @default(now()) @db.Timestamptz(6)
+# Common service
+LOGGER_KAFKA_TOPIC=project-logs-common
+```
 
-          @@schema("public")
+### 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
+
+All logs are automatically normalized before being sent to transports:
+
+```typescript
+// You can pass Error objects or LogData with errors
+this.logger.error(new Error('Something went wrong'), {
+  userId: 123,
+});
+
+// LoggerService automatically:
+// 1. Serializes the Error to SerializedError
+// 2. Creates NormalizedLog with all required fields
+// 3. Sends to all transports
+```
+
+### NormalizedLog Structure
+
+```typescript
+interface NormalizedLog {
+  timestamp: number;           // Unix timestamp in milliseconds
+  level: LogLevel;             // 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'emergency'
+  message: string;             // Log message
+  organization?: string;       // From config
+  context?: string;            // From config
+  app?: string;                // From config
+  sourceClass?: string;        // Auto-detected from class name
+  correlationId?: string;      // From CLS (can be undefined)
+  error?: SerializedError;      // Serialized error (never raw Error)
+  props?: Record<string, any>;  // Custom properties
+  durationMs?: number;         // Duration in milliseconds
+  label?: string;              // Auto-generated: `${organization}.${context}.${app}`
+  stack?: string;              // Error stack trace (if error present)
+}
+```
+
+### Error Serialization
+
+Errors are automatically serialized using `serializeError()`:
+
+```typescript
+import { serializeError } from '@infineit/winston-logger';
+
+const error = new Error('Test error');
+error.code = 'ERR_TEST';
+
+const serialized = serializeError(error);
+// {
+//   name: 'Error',
+//   message: 'Test error',
+//   stack: 'Error: Test error\n    at ...',
+//   code: 'ERR_TEST'
+// }
+```
+
+**Important**: If you pass errors in `LogData`, they must already be serialized:
+
+```typescript
+import { serializeError } from '@infineit/winston-logger';
+
+const error = new Error('Test');
+this.logger.info('Message', {
+  error: serializeError(error),  // Must serialize manually if in LogData
+});
+```
+
+---
+
+## Correlation ID (CLS)
+
+### Automatic Retrieval
+
+`LoggerService` automatically retrieves correlation ID from CLS:
+
+```typescript
+// If CLS is configured, correlationId is automatically included
+this.logger.info('Message');
+// Log includes: { correlationId: '...' } (from CLS)
+```
+
+### Manual Setting (Non-HTTP Contexts)
+
+For non-HTTP contexts (Kafka, Bull, CRON, CLI), set correlation ID manually:
+
+```typescript
+import { ContextStorageService } from '@infineit/winston-logger';
+
+constructor(
+  private readonly logger: LoggerService,
+  private readonly contextStorage: ContextStorageService,
+) {}
+
+async processMessage(message: Message) {
+  // Set correlation ID from message
+  this.contextStorage.setContextId(message.correlationId);
+  
+  this.logger.info('Processing message');
+  // Log includes: { correlationId: message.correlationId }
+}
+```
+
+### Optional Correlation ID
+
+Correlation ID is **optional** - `undefined` is valid:
+
+```typescript
+// If no correlation ID is set, logs will have:
+// { correlationId: undefined }
+// This is perfectly valid and expected in some contexts
+```
+
+### HTTP Context Setup
+
+For HTTP services, configure CLS middleware:
+
+```typescript
+import { ClsModule } from 'nestjs-cls';
+import { v4 as uuidv4 } from 'uuid';
+
+@Module({
+  imports: [
+    ClsModule.forRoot({
+      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();
+        },
+      },
+    }),
+    ContextModule,  // Provides CLS service
+    LoggerModule.forRoot(),
+  ],
+})
+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;
       }
-  ```
-## Inspiration
+      
+      // 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;
+    }
+  }
+}
+```
 
-This project is inspired by the excellent work from:
+### Kafka Producer - Propagating Correlation ID
 
-- [Medium](https://medium.com/@jose-luis-navarro/logging-on-nestjs-like-a-pro-with-correlation-ids-log-aggregation-winston-morgan-and-more-d03e3bb56772)
-- [Logger](https://github.com/jnm733/nestjs-logger/tree/main)
-- [winston-pg](https://github.com/InnovA2/winston-pg/tree/main)
+**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
+
+### 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 { ContextModule, LoggerModule } from '@infineit/winston-logger';
+
+@Module({
+  imports: [
+    ContextModule,
+    LoggerModule.forRoot(),
+  ],
+})
+export class AppModule {}
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  
+  // ✅ No app.useLogger() needed - LoggerService is automatically available
+  // ✅ No app.flushLogs() needed - logging is fire-and-forget
+  
+  await app.listen(3000);
+}
+
+bootstrap();
+```
+
+### Using LoggerService in Your Code
+
+```typescript
+// ✅ CORRECT: Inject LoggerService
+import { Injectable } from '@nestjs/common';
+import { LoggerService } from '@infineit/winston-logger';
+
+@Injectable()
+export class MyService {
+  constructor(private readonly logger: LoggerService) {}
+
+  doSomething() {
+    // ✅ Logging is automatic and fire-and-forget
+    this.logger.info('Processing started');
+    
+    // ✅ No need to flush - logs are sent immediately
+    // ✅ No need to await - logging is non-blocking
+  }
+}
+```
+
+### Comparison Table
+
+| Feature | Old (Deprecated) ❌ | New (Current) ✅ |
+|---------|---------------------|------------------|
+| **Setup** | `app.useLogger(...)` | `LoggerModule.forRoot()` in imports |
+| **Flush** | `app.flushLogs()` required | Not needed (fire-and-forget) |
+| **Usage** | Direct logger access | Inject `LoggerService` |
+| **HTTP Only** | Yes (assumed HTTP runtime) | No (works in all contexts) |
+| **Middleware** | Auto-mounted | Manual configuration |
+| **Transports** | Winston only | Pluggable `LoggerTransport[]` |
+| **Blocking** | Could block with `flushLogs()` | Always non-blocking |
+| **Context Support** | HTTP only | HTTP, Kafka, Bull, CRON, CLI |
+
+### Key Changes Summary
+
+#### ❌ What's Removed
+
+- `app.useLogger()` - **No longer exists**
+- `app.flushLogs()` - **No longer exists**
+- HTTP-only assumptions - **Removed**
+- Auto-mounted middleware - **Removed**
+
+#### ✅ What's New
+
+- **LoggerService injection** - Inject `LoggerService` into your classes
+- **Multi-context support** - Works in HTTP, Kafka, Bull, CRON, CLI
+- **Transport architecture** - Pluggable transports via `LoggerTransport[]`
+- **Automatic normalization** - Logs are normalized before transport
+- **CLS integration** - Correlation ID support via AsyncLocalStorage
+
+### Migration Steps
+
+1. **Remove `app.useLogger()` calls**
+   ```typescript
+   // ❌ Remove this
+   app.useLogger(app.get(LoggerModule));
+   ```
+
+2. **Remove `app.flushLogs()` calls**
+   ```typescript
+   // ❌ Remove this
+   app.flushLogs();
+   ```
+
+3. **Add LoggerModule to imports**
+   ```typescript
+   @Module({
+     imports: [
+       ContextModule,  // Required for CLS
+       LoggerModule.forRoot(),  // Add this
+     ],
+   })
+   export class AppModule {}
+   ```
+
+4. **Inject LoggerService instead of direct logger access**
+   ```typescript
+   // ❌ Old way (if you had direct logger access)
+   // logger.info('message');
+   
+   // ✅ New way
+   constructor(private readonly logger: LoggerService) {}
+   this.logger.info('message');
+   ```
+
+5. **Configure CLS middleware (for HTTP services)**
+   ```typescript
+   // ✅ Add CLS middleware configuration
+   ClsModule.forRoot({
+     middleware: {
+       mount: true,
+       generateId: true,
+     },
+   }),
+   ```
+
+### Reassurance: Nothing Breaks
+
+**Good news**: Your existing logging calls will continue to work! The only changes needed are:
+
+1. ✅ Remove `app.useLogger()` and `app.flushLogs()` calls
+2. ✅ Add `LoggerModule.forRoot()` to your module imports
+3. ✅ Inject `LoggerService` where you need logging
+
+**Logging behavior**:
+- ✅ Still fire-and-forget (no `flushLogs()` needed)
+- ✅ Still non-blocking
+- ✅ Still failure-safe (errors are swallowed)
+- ✅ Still works in all contexts (HTTP, Kafka, Bull, etc.)
+
+**No breaking changes to logging API**:
+- ✅ Same log levels: `debug`, `info`, `warn`, `error`, `fatal`, `emergency`
+- ✅ Same method signatures
+- ✅ Same `LogData` structure
+- ✅ Same error handling
+
+### Example: Complete Migration
+
+**Before (Deprecated)**:
+```typescript
+import { NestFactory } from '@nestjs/core';
+import { LoggerModule } from '@infineit/winston-logger';
+
+@Module({
+  imports: [LoggerModule],
+})
+export class AppModule {}
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  app.useLogger(app.get(LoggerModule));  // ❌ Remove
+  await app.listen(3000);
+  app.flushLogs();  // ❌ Remove
+}
+```
+
+**After (Current)**:
+```typescript
+import { NestFactory } from '@nestjs/core';
+import { ClsModule } from 'nestjs-cls';
+import { ContextModule, LoggerModule } from '@infineit/winston-logger';
+
+@Module({
+  imports: [
+    ClsModule.forRoot({
+      middleware: { mount: true, generateId: true },
+    }),
+    ContextModule,  // ✅ Add
+    LoggerModule.forRoot(),  // ✅ Add
+  ],
+})
+export class AppModule {}
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  // ✅ No app.useLogger() needed
+  await app.listen(3000);
+  // ✅ No app.flushLogs() needed
+}
+```
+
+### Need Help?
+
+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
+
+---
+
+## Best Practices
+
+### 1. Fire-and-Forget Logging
+
+✅ **DO**: Log without awaiting
+```typescript
+this.logger.info('Processing started');
+// Continue with business logic immediately
+```
+
+❌ **DON'T**: Try to await logging (methods return `void`)
+```typescript
+// This won't work - logger methods return void
+await this.logger.info('Message');  // ❌
+```
+
+### 2. Error Handling
+
+✅ **DO**: Pass Error objects directly
+```typescript
+try {
+  // ...
+} catch (error) {
+  this.logger.error(error, { userId: 123 });
+}
+```
+
+✅ **DO**: Include context in error logs
+```typescript
+this.logger.error(error, {
+  userId: 123,
+  orderId: 456,
+  action: 'process-payment',
+});
+```
+
+### 3. Structured Logging
+
+✅ **DO**: Use `props` for structured data
+```typescript
+this.logger.info('User logged in', {
+  props: {
+    userId: 123,
+    email: 'user@example.com',
+    ipAddress: '192.168.1.1',
+  },
+});
+```
+
+### 4. Correlation ID
+
+✅ **DO**: Set correlation ID in non-HTTP contexts
+```typescript
+// Kafka consumer
+this.contextStorage.setContextId(message.correlationId);
+
+// Bull worker
+this.contextStorage.setContextId(job.id.toString());
+```
+
+✅ **DO**: Use correlation ID for request tracing
+```typescript
+// All logs in the same request/job will have the same correlationId
+this.logger.info('Step 1');
+this.logger.info('Step 2');
+// Both logs have the same correlationId
+```
+
+### 5. Performance Logging
+
+✅ **DO**: Include duration for performance monitoring
+```typescript
+const start = Date.now();
+await this.processData();
+this.logger.info('Processing completed', {
+  durationMs: Date.now() - start,
+});
+```
+
+---
+
+## Forbidden Actions
+
+### ❌ DO NOT: Add Database Dependencies
+
+```typescript
+// ❌ FORBIDDEN: Do not add Prisma, TypeORM, Mongoose, etc.
+import { PrismaClient } from '@prisma/client';
+```
+
+**Why**: The logger must work in all contexts without database assumptions.
+
+### ❌ DO NOT: Access HTTP Objects
+
+```typescript
+// ❌ FORBIDDEN: Do not inject HttpAdapterHost, Request, Response
+constructor(
+  private readonly httpAdapter: HttpAdapterHost,  // ❌
+) {}
+```
+
+**Why**: The logger must work in non-HTTP contexts (Kafka, Bull, CRON, CLI).
+
+### ❌ DO NOT: Auto-Mount Middleware
+
+```typescript
+// ❌ FORBIDDEN: Do not implement NestModule or configure middleware
+export class LoggerModule implements NestModule {  // ❌
+  configure(consumer: MiddlewareConsumer) {  // ❌
+    consumer.apply(...).forRoutes('*');
+  }
+}
+```
+
+**Why**: Applications must configure middleware themselves for flexibility.
+
+### ❌ DO NOT: Generate Correlation ID
+
+```typescript
+// ❌ FORBIDDEN: Do not generate correlation ID in logger
+import { v4 as uuidv4 } from 'uuid';
+const correlationId = uuidv4();  // ❌
+```
+
+**Why**: Correlation ID must come from CLS or be set by the application.
+
+### ❌ DO NOT: Throw Errors
+
+```typescript
+// ❌ FORBIDDEN: Do not throw errors in logging code
+if (!transport) {
+  throw new Error('Transport not found');  // ❌
+}
+```
+
+**Why**: Logging failures must never break business logic. All errors are swallowed.
+
+### ❌ DO NOT: Use Async/Await in Logging
+
+```typescript
+// ❌ FORBIDDEN: Do not use async/await in logging
+async log(...) {  // ❌
+  await this.transport.send(...);
+}
+```
+
+**Why**: Logging must be fire-and-forget and non-blocking.
+
+---
+
+## Examples
+
+### Complete HTTP Service Example
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { ClsModule } from 'nestjs-cls';
+import { v4 as uuidv4 } 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) => 
+          req.headers['x-correlation-id'] as string || uuidv4(),
+      },
+    }),
+    ContextModule,
+    LoggerModule.forRoot({
+      nodeEnv: process.env.NODE_ENV,
+      organization: 'my-org',
+      context: 'user-service',
+      app: 'api',
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { LoggerService } from '@infineit/winston-logger';
+
+@Injectable()
+export class UserService {
+  constructor(private readonly logger: LoggerService) {}
+
+  async findById(id: string) {
+    this.logger.info('Fetching user', { userId: id });
+    
+    try {
+      const user = await this.repository.findById(id);
+      this.logger.info('User found', { userId: id });
+      return user;
+    } catch (error) {
+      this.logger.error(error, { userId: id });
+      throw error;
+    }
+  }
+}
+```
+
+### Complete Kafka Consumer Example
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { KafkaListener } from '@nestjs/microservices';
+import { LoggerService, ContextStorageService } from '@infineit/winston-logger';
+
+@Injectable()
+export class OrderConsumer {
+  constructor(
+    private readonly logger: LoggerService,
+    private readonly contextStorage: ContextStorageService,
+  ) {}
+
+  @KafkaListener('order.created')
+  async handleOrderCreated(message: OrderCreatedEvent) {
+    // Set correlation ID from message
+    this.contextStorage.setContextId(message.correlationId || message.id);
+    
+    const start = Date.now();
+    this.logger.info('Processing order', {
+      orderId: message.id,
+      userId: message.userId,
+    });
+
+    try {
+      await this.processOrder(message);
+      
+      this.logger.info('Order processed', {
+        orderId: message.id,
+        durationMs: Date.now() - start,
+      });
+    } catch (error) {
+      this.logger.error(error, {
+        orderId: message.id,
+        durationMs: Date.now() - start,
+      });
+      throw error;
+    }
+  }
+}
+```
+
+### Custom Transport Example
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { LoggerTransport, NormalizedLog } from '@infineit/winston-logger';
+import { KafkaProducer } from './kafka-producer';
+
+@Injectable()
+export class KafkaLogTransport implements LoggerTransport {
+  constructor(private readonly kafkaProducer: KafkaProducer) {}
+
+  log(normalizedLog: NormalizedLog): void {
+    try {
+      // Fire-and-forget: send to Kafka without awaiting
+      this.kafkaProducer.send({
+        topic: 'application-logs',
+        messages: [{
+          key: normalizedLog.correlationId || 'no-correlation-id',
+          value: JSON.stringify(normalizedLog),
+          timestamp: normalizedLog.timestamp.toString(),
+        }],
+      });
+    } catch (error) {
+      // Swallow errors - never break business logic
+      console.error('KafkaLogTransport error (swallowed):', error);
+    }
+  }
+}
+```
+
+```typescript
+import { Provider } from '@nestjs/common';
+import { LoggerModule } from '@infineit/winston-logger';
+import { KafkaLogTransport } from './kafka-log-transport';
+
+const customTransports: Provider[] = [
+  {
+    provide: KafkaLogTransport,
+    useClass: KafkaLogTransport,
+  },
+];
+
+@Module({
+  imports: [
+    LoggerModule.forRoot(config, customTransports),
+  ],
+})
+export class AppModule {}
+```
+
+---
 
 ## License
 
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
+MIT
 
 ## Author
 
-Dharmesh Patel 🇮🇳 <br>
-- [GitHub](https://github.com/dharmesh-r-patel/nestjs-starter)
-- [LinkedIn](https://www.linkedin.com/in/dharmeshbbay)
-- [Instagram](https://www.instagram.com/dharmesh_numbertank)
+Dharmesh Patel
+
+## Repository
+
+https://github.com/dharmesh-r-patel/nestjs-logger
+