Logging Correlation IDs Effectively in NestJS

Recently, I had to add correlation IDs to the logs of one of our micro-services, which is built with NestJS. My first instinct was to manually add correlation ID to each message before passing it to the logger, but then, I reminded myself that I code for a living - so I should be automating this. Thus, I started the adventure and did what used to be every developer’s first instinct before AI overhaul, a Google search. The only thing I found was the nestjs-pino package but I was not ready to moving this component to JSON logging yet. Thus, I decided to implement the solution myself and write an article for those coming after me.

Solution 1: Custom Logger with Request Scope

My first thought was to implement a custom logger with the injection scope of Request. Basically, instantiating a new instance of the logger for each request and using the correlation id within that request to print all logs. The problem with this approach is, not only will we be creating a new instance of the logger for each request, but also all the classes in which our logger will be injected in. In other words, for each request we will be instantiating a new dependency tree, which can cause performance issues. You can read more about this performance concern here.

Solution 2: Using AsyncLocalStorage

The preferable option, which we will be implementing here, is to use the AsyncLocalStorage. It allows us to maintain a distinct state for each request throughout its lifetime. We will create a middleware that will store the correlation ID of each request in this store, which can be easily accessed later for logging (or other) purposes.

Creating the Async Store

Let’s start by creating a new instance of the AsyncLocalStorage class. We will use this instance only for our logger and just to store the correlation IDs, hence the type UUID.

// src/custom-logger/asyncLocalStorage.ts
import { AsyncLocalStorage } from 'async_hooks';
import { UUID } from 'crypto';

export const asyncStore: AsyncLocalStorage<UUID> = new AsyncLocalStorage();

Creating Custom Logger Module with the Middleware

Next up, we need to create a module for our custom logger with the middleware that will store correlation ID for each request in our asyncStore. This middleware works for all routes and generates a new correlation ID if it does not already exist in the request headers.

I am assuming that the correlation ID will be provided in the x-correlation-id header. If yours is different, adjust the implementation accordingly.

You can use Nest CLI to create the modules and providers, but in this article I will be creating everything manually.

// src/custom-logger/custom-logger.module.ts
import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';
import { randomUUID, UUID } from 'crypto';
import { asyncStore } from './asyncLocalStorage';

@Module({
  providers: [],
})
export class CustomLoggerModule implements NestModule {

  configure(consumer: MiddlewareConsumer) {
    // bind the middleware,
    consumer
      .apply((req: Request, res: Response, next: NextFunction) => {
        let correlationId = req.headers['x-correlation-id'] as UUID;

        if (!correlationId) {
          correlationId = randomUUID();
        }

        asyncStore.run(correlationId, () => next());
      })
      .forRoutes('*');
  }
}

Implementing the Custom Logger

It is now time for the main event - implementation of our custom logger. Rather than implementing it from scratch, I think it is better if we just add the correlation ID to the message and let the default logger handle the rest. This way we will fulfill our use-case without reinventing the wheel. That is exactly what the below implementation of the logger does.

The CustomLogger extends the ConsoleLogger class, appends a correlation ID to each message, and then forwards it to the original function for execution. The addCorrelationIdToMessage method defines how the correlation ID should be printed. Currently, it appears after the context, as shown below. If you prefer a different format, simply modify this method, and the change will apply everywhere.

[Nest] 344125  - 03/16/2025, 2:11:13 AM     LOG [SampleService] [CID: 3896b709-1a91-469c-b813-062c0334a808] log from the sample service

Every instance of this logger uses the same asyncStore that we created previously to retrieve correlation IDs. Additionally, it provides a getCorrelationId method to retrieve the correlation ID for use outside the logger's scope if needed.

// src/custom-logger/custom-logger.ts
import {
  ConsoleLogger,
  ConsoleLoggerOptions,
  Injectable,
  LoggerService,
  Scope,
} from '@nestjs/common';
import { AsyncLocalStorage } from 'async_hooks';
import { UUID } from 'crypto';
import { asyncStore } from './asyncLocalStorage';

@Injectable({ scope: Scope.TRANSIENT })
export class CustomLogger extends ConsoleLogger implements LoggerService {
  private readonly als: AsyncLocalStorage<UUID> = asyncStore;

  constructor();
  constructor(context: string);
  constructor(options: ConsoleLoggerOptions);
  constructor(context: string, options: ConsoleLoggerOptions);
  constructor(
    context?: string | ConsoleLoggerOptions,
    options?: ConsoleLoggerOptions,
  ) {
    if (context && options) {
      super(context as string, options);
    } else if (context) {
      super(context as string);
    } else {
      super();
    }
  }

  getCorrelationId(): UUID | undefined {
    return this.als.getStore();
  }

  addCorrelationIdToMessage(message: any): any {
    const correlationId = this.getCorrelationId();
    return correlationId ? `[CID: ${correlationId}] ${message}` : message;
  }

  log(message: any, context?: string): void;
  log(message: any, ...optionalParams: [...any, string?]): void;
  log(message: any, ...optionalParams: [...any, string?]) {
    super.log(this.addCorrelationIdToMessage(message), ...optionalParams);
  }

  error(message: any, stackOrContext?: string): void;
  error(message: any, stack?: string, context?: string): void;
  error(message: any, ...optionalParams: [...any, string?, string?]): void;
  error(message: any, ...optionalParams: [...any, string?, string?]) {
    super.error(this.addCorrelationIdToMessage(message), ...optionalParams);
  }

  warn(message: any, context?: string): void;
  warn(message: any, ...optionalParams: [...any, string?]): void;
  warn(message: any, ...optionalParams: [...any, string?]) {
    super.warn(this.addCorrelationIdToMessage(message), ...optionalParams);
  }

  debug(message: any, context?: string): void;
  debug(message: any, ...optionalParams: [...any, string?]): void;
  debug(message: any, ...optionalParams: [...any, string?]) {
    super.debug(this.addCorrelationIdToMessage(message), ...optionalParams);
  }

  verbose(message: any, context?: string): void;
  verbose(message: any, ...optionalParams: [...any, string?]): void;
  verbose(message: any, ...optionalParams: [...any, string?]) {
    super.verbose(this.addCorrelationIdToMessage(message), ...optionalParams);
  }

  fatal(message: any, context?: string): void;
  fatal(message: any, ...optionalParams: [...any, string?]): void;
  fatal(message: any, ...optionalParams: [...any, string?]) {
    super.fatal(this.addCorrelationIdToMessage(message), ...optionalParams);
  }
}

Importing the Custom Logger

Our implementation is now complete; we just need to add a few imports. First, let's import the CustomLogger into our CustomLoggerModule. The updated module file will now look like this:

// src/custom-logger/custom-logger.module.ts
import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
import { CustomLogger } from './custom-logger';        // ADDED
import { Request, Response, NextFunction } from 'express';
import { randomUUID, UUID } from 'crypto';
import { asyncStore } from './asyncLocalStorage';

@Module({
  providers: [CustomLogger],                           // UPDATED
})
export class CustomLoggerModule implements NestModule {
  constructor(private readonly logger: CustomLogger) { // ADDED
    logger.setContext(CustomLoggerModule.name);        // ADDED
  }                                                    // ADDED

  configure(consumer: MiddlewareConsumer) {
    // bind the middleware,
    consumer
      .apply((req: Request, res: Response, next: NextFunction) => {
        let correlationId = req.headers['x-correlation-id'] as UUID;

        if (!correlationId) {
          correlationId = randomUUID();
          this.logger.log(
            `x-correlation-id not found in the request header.Generated a new one: ${correlationId}`,
          );                                           // ADDED
        }

        asyncStore.run(correlationId, () => next());
      })
      .forRoutes('*');
  }
}

Similarly, we will need to import CustomLoggerModule in our AppModule to ensure that this module is within the app’s scope. After updating, the app.module.ts file should look something like:

// src/app.module.ts
import { CustomLoggerModule } from './custom-logger/custom-logger.module';
/*    OTHER IMPORTS    */

@Module({
  imports: [
    CustomLoggerModule,
/*    OTHER MODULES    */
  ]
})
export class AppModule {}

Usage

Our custom logger is now complete and ready to be used (🎉). All you have to do now, is create an instance of it in your providers and use it just like the default logger - it will automatically print correlation ID with each message. Here is an example.

import { Controller, Get } from '@nestjs/common';
import { SampleService } from './sample.service';
import { CustomLogger } from 'src/custom-logger/custom-logger';

@Controller('sample')
export class SampleController {
  private readonly logger = new CustomLogger(SampleController.name);  // INSTANTIATE

  constructor(private readonly sampleSerivce: SampleService) {}

  @Get()
  getHello(): string {
    this.logger.log('LOG TEST');                                      // USE
    this.logger.debug('DEBUG TEST');                                  // USE
    this.logger.error('ERROR TEST', new Error('Error test').stack);   // USE
    this.logger.fatal('FATAL TEST');                                  // USE
    this.logger.warn('WARN TEST');                                    // USE
    this.logger.verbose('VERBOSE TEST');                              // USE

    return this.sampleSerivce.getHello();
  }
}

Final Words

Complete code of this project is available here. Thank you for reading.