@infineit/winston-logger 1.0.29 → 1.0.31

package/README.md

@@ -1,169 +1,1283 @@
-<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
+- ✅ **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
+- ✅ **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)
+- [Log Normalization](#log-normalization)
+- [Correlation ID (CLS)](#correlation-id-cls)
+- [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)
+};
+
+@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
+```
+
+```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,
+}));
+```
+
+```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 |
+
+### 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
+
+---
+
+## 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
+
+---
+
+## 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 {}
+```
+
+---
+
+## 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
 
-- `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`.
+```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
+}
+```
 
-## Project structure
+#### LogData
 
-## Key concepts
+```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
+}
+```
 
-### NestJS Logger
+### ContextStorageService
 
-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.
+Service for managing CLS context (correlation ID).
 
-We pass that adapter to the NestJS app on the `main.ts` file.
+#### Methods
 
-### Correlation IDs
+```typescript
+// Get correlation ID from CLS
+getContextId(): string | undefined
 
-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.
+// Set correlation ID in CLS
+setContextId(id: string): void
 
-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.
+// Get any value from CLS
+get<T>(key: string): T | undefined
 
-### Context Wrapper
+// Set any value in CLS
+set<T>(key: string, value: T): void
+```
 
-To add custom data to all the logs, we use a wrapper `LoggerContextWrapper`.
+---
 
-That class is injected with a Transient scope. By that, we can get the caller class and add it to the logs.
+## Migration Guide (Legacy app.useLogger Users)
 
-## Prisma Table
+### ⚠️ Deprecated: app.useLogger() and app.flushLogs()
 
-  ```
-      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)
+If you're migrating from an older version of `@infineit/winston-logger` that used `app.useLogger()` and `app.flushLogs()`, this section is for you.
 
-          @@schema("public")
-      }
-  ```
-## Inspiration
+**Status**: These methods have been **removed** and are **no longer available**.
 
-This project is inspired by the excellent work from:
+### Why Was It Removed?
 
-- [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)
+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
+