NestJs Trace ID

NestJs module that creates or use an identifier for each request and also send this to other microservices through the @nestjs/axios layer, in order to have a distributed identifier. Really usefull when you need to follow specific workflow of a request in logs.

This uses the AsyncLocalStorage and was inspired in this repository https://github.com/abonifacio/nestjs-request-context

Usage

In your app.module.ts file do the following

...
import { TraceIdModule } from 'nestjs-trace-id';
...
@Module({
  imports: [
    ...
      TraceIdModule,
    ...
  ], 
  providers: [...],
  controllers: [..],
})
export class AppModule {}

Once you added the module, you can set the header X-Trace-Id in your request or it will be generated automatically using a random UUID. This header will be propagated to the requests made by httpService and the generated trace id will be available on the final response too.

Examples

Let's say that your NestJs app has a route under https://localhost:4000/somewhere:

// Example of autogenerated uuid
curl -I localhost:4000/somewhere
HTTP/1.1 200 OK
X-Trace-Id: 8120dbf5-9054-4516-b602-6a6bd118ce5a
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 43
ETag: W/"2b-hGShxOkieaAVDloBubJVM+h58D8"
Date: Fri, 09 Sep 2022 18:48:20 GMT
Connection: keep-alive
Keep-Alive: timeout=5

// Example of custom trace id
curl -H "X-Trace-Id: Example" -I http://localhost:4000/somewhere
HTTP/1.1 200 Ok
X-Trace-Id: Example
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 43
ETag: W/"2b-hGShxOkieaAVDloBubJVM+h58D8"
Date: Fri, 09 Sep 2022 18:51:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5

Miscelaneus

Setup traceId in your Pino Logs

If you are using Pino for logging, you can setup the traceId in the logs in order to help while you're debugging your application:

...
import { TraceIdModule, TraceIdMiddleware } from 'nestjs-trace-id';
...
@Module({
  imports: [
    ...
      TraceIdModule,
      LoggerModule.forRoot({
        ...
        pinoHttp: {
          ...
          customProps: (req: Request) => ({
            traceId: req[TraceIdMiddleware.Header],
          }),
          ...
        },
        ...
      }),
    ...
  ], 
  providers: [...],
  controllers: [..],
})
export class AppModule {}

Accessing to the trace id

You can also access to request identifier if you need to pass to somewhere

import { TraceIdMiddleware } from './trace-id.middleware';

@Controller('/somewhere')
export class SomeController {
...

  @Get()
  someName(@Req() req) {
    ...
    const traceId = req[TraceIdMiddleware.Header]
    ...
  }
}

Release Notes

1.0.0

First version