![\"Bombed](\"https://upload.wikimedia.org/wikipedia/commons/thumb/3/32/Vovchansk_%282024-06-02%29_1513.jpg/960px-Vovchansk_%282024-06-02%29_1513.jpg\"/)
\n \n \"Vovchansk (2024-06-02) 1513\" by National Police of Ukraine (Liut Brigade) is licensed under CC BY 4.0.\n
\n \n
\n \"Vovchansk (2024-06-02) 1513\" by National Police of Ukraine (Liut Brigade) is licensed under CC BY 4.0.\n
\n This is Vovchansk, Ukraine, the city where the father of this libraryβs author was born. This is how it looks now, after the Russian invasion. If you find this library useful and would like to thank the author, please consider donating any amount via one of the following links:\n
\n γ»Armed Forces of Ukraineγ»\"The Come Back Alive\" foundationγ»\n
\n Thanks for your support! πΊπ¦\n
\n \n ![\"npm\"](\"https://img.shields.io/npm/v/nestjs-pino\")
![\"npm\"](\"https://img.shields.io/npm/dm/nestjs-pino\")
\n \n \n
![\"Code](\"https://qlty.sh/gh/iamolegga/projects/nestjs-pino/coverage.svg\")
\n \n \n ![\"Known](\"https://snyk.io/test/github/iamolegga/nestjs-pino/badge.svg\"){kind=icon}
\n \n \n ![\"Libraries.io\"](\"https://img.shields.io/librariesio/release/npm/nestjs-pino\")
\n
![\"Supported](\"https://img.shields.io/badge/platforms-Express%20%26%20Fastify-green\"){kind=icon}
β¨β¨β¨ Platform agnostic logger for NestJS based on Pino with REQUEST CONTEXT IN EVERY LOG β¨β¨β¨
\n\n---\n\nThis is the documentation for v5. Compatibility with earlier majors:
\n\n| nestjs-pino | NestJS | pino | pino-http | Node.js |\n| ----------- | ------------ | ------------ | ----------------------------- | -------- |\n| v5 | 11.0.8+, 12.0.2+ | 10 | 11 | >=22.12 |\n| [v4](https://github.com/iamolegga/nestjs-pino/tree/v4.6.1#readme) | 8, 9, 10, 11 | 7.5+, 8, 9, 10 | 6.4+, 7, 8, 9, 10, 11 | >=14 |\n| [v1](https://github.com/iamolegga/nestjs-pino/tree/v1.4.0#readme) | < 8 | | | |\n\n---\n\n## Install\n\n```sh\nnpm i nestjs-pino pino-http\n```\n\n## Example\n\nFirstly, import module with `LoggerModule.forRoot(...)` or `LoggerModule.forRootAsync(...)` only once in root module (check out module configuration docs [below](#configuration)):\n\n```ts\nimport { LoggerModule } from 'nestjs-pino';\n\n@Module({\n imports: [LoggerModule.forRoot()],\n})\nclass AppModule {}\n```\n\nSecondly, set up app logger:\n\n```ts\nimport { Logger } from 'nestjs-pino';\n\nconst app = await NestFactory.create(AppModule, { bufferLogs: true });\napp.useLogger(app.get(Logger));\n```\n\nNow you can use one of the loggers:\n\n```ts\n// NestJS standard built-in logger.\n// Logs will be produced by pino internally\nimport { Logger } from '@nestjs/common';\n\nexport class MyService {\n private readonly logger = new Logger(MyService.name);\n foo() {\n // All logger methods have args format the same as pino, but pino methods\n // `trace` and `info` are mapped to `verbose` and `log` to satisfy\n // `LoggerService` interface of NestJS:\n this.logger.verbose({ foo: 'bar' }, 'baz %s', 'qux');\n this.logger.debug('foo %s %o', 'bar', { baz: 'qux' });\n this.logger.log('foo');\n }\n}\n```\n\nUsage of the standard logger is recommended and idiomatic for NestJS. But there is one more option to use:\n\n```ts\nimport { PinoLogger, InjectPinoLogger } from 'nestjs-pino';\n\nexport class MyService {\n constructor(\n private readonly logger: PinoLogger\n ) {\n // Optionally you can set context for logger in constructor or ...\n this.logger.setContext(MyService.name);\n }\n\n constructor(\n // ... set context via special decorator\n @InjectPinoLogger(MyService.name)\n private readonly logger: PinoLogger\n ) {}\n\n foo() {\n // PinoLogger has same methods as pino instance\n this.logger.trace({ foo: 'bar' }, 'baz %s', 'qux');\n this.logger.debug('foo %s %o', 'bar', { baz: 'qux' });\n this.logger.info('foo');\n }\n}\n```\n\n> [!WARNING]\n> Register `LoggerModule` **only** via `forRoot(...)` / `forRootAsync(...)`, and\n> **only once**, in the root module. Never add the bare `LoggerModule` class to a\n> feature module's `imports`, not even just to inject `PinoLogger`. Because\n> `LoggerModule` is `@Global()`, both `Logger` and `PinoLogger` are already\n> available everywhere after the single root registration, so you never need to\n> re-import it. A bare import instantiates the module a second time, which\n> registers the `pino-http` middleware **again** and makes every request log\n> **twice**. The failure is completely silent: no compile error, no injection\n> failure, no warning\n> ([#3074](https://github.com/iamolegga/nestjs-pino/issues/3074)).\n\n### Drop-in replacement: NativeLogger\n\n`NativeLogger` is a **drop-in replacement** for NestJS's built-in `ConsoleLogger`. It produces **identical JSON output** β same field names, same argument handling, same error format β but powered by pino with request context in every log.\n\nIf you're already using `ConsoleLogger` with `{ json: true }` and want to switch to pino without changing any of your logging code, this is for you:\n\n```ts\nimport { NativeLogger, nativeLoggerOptions } from 'nestjs-pino';\n\n@Module({\n imports: [LoggerModule.forRoot({ pinoHttp: nativeLoggerOptions })],\n})\nclass AppModule {}\n\nconst app = await NestFactory.create(AppModule, { bufferLogs: true });\napp.useLogger(app.get(NativeLogger));\n```\n\nThat's it. Your existing `new Logger(MyService.name)` calls throughout the codebase will work exactly as before β same `message`, `context`, `level`, `timestamp`, `pid`, and `stack` fields β but now with pino's performance and automatic request context binding.\n\n**ConsoleLogger JSON output:**\n```json\n{\"level\":\"log\",\"pid\":17580,\"timestamp\":1765305000999,\"message\":\"Hello World\",\"context\":\"AppService\"}\n```\n\n**NativeLogger + nativeLoggerOptions output:**\n```json\n{\"level\":\"log\",\"pid\":17580,\"timestamp\":1765305000999,\"message\":\"Hello World\",\"context\":\"AppService\"}\n```\n\n#### How it differs from `Logger`\n\n- **`Logger`** (pino-native): treats extra arguments as pino interpolation values. `this.logger.log('foo %s', 'bar')` β `{\"msg\":\"foo bar\"}`\n- **`NativeLogger`** (NestJS-native): parses arguments the way `ConsoleLogger` does. `this.logger.log('foo', 'bar', 'Ctx')` β two logs, `{\"message\":\"foo\",\"context\":\"Ctx\"}` and `{\"message\":\"bar\",\"context\":\"Ctx\"}`\n\n#### What matches ConsoleLogger exactly\n\n- Argument parsing: last string = context, rest = separate log entries\n- Structured params: on NestJS 12, plain objects after the message are merged into a single `params` field on one entry (`ConsoleLoggerOptions.structuredParams`, on by default) β `this.logger.log('foo', { a: 1 }, { b: 2 })` β `{\"message\":\"foo\",\"params\":{\"a\":1,\"b\":2}}`. On NestJS 11 each of them is a separate entry. `NativeLogger` follows the `ConsoleLogger` of the NestJS version you actually have, so out of the box there is nothing to configure β see below to override it\n- Error handling: `this.logger.error('msg', stackTrace, 'Ctx')` β `{\"message\":\"msg\",\"stack\":\"Error: ...\",\"context\":\"Ctx\"}`\n- Error objects: `this.logger.log(new Error('oops'))` β full error+stack as message string\n- Exception handler: thrown errors logged with full stack in `message` field\n- Object messages: `this.logger.log({ foo: 'bar' })` β `{\"message\":{\"foo\":\"bar\"}}`\n- Field names (with `nativeLoggerOptions`): `message`, `timestamp`, `pid`, `level`, `context`, `stack`\n\n#### Keeping your ConsoleLogger options\n\nIf your application configures `ConsoleLogger` rather than relying on its\ndefaults, pass the same values to keep the output identical after the switch:\n\n```ts\nLoggerModule.forRoot({\n pinoHttp: nativeLoggerOptions,\n nativeLogger: {\n // NestJS 12 default is `true`, NestJS 11 has no such option and behaves\n // as `false`. Omit it to follow the ConsoleLogger you actually have.\n structuredParams: true,\n // Spread params into the root of the record instead of nesting them\n // under `params`. NestJS default is `false`.\n flattenParams: true,\n },\n});\n```\n\n```json\n{\"level\":\"log\",\"message\":\"foo\",\"context\":\"AppService\",\"a\":1,\"b\":2}\n```\n\nUnlike NestJS, both options are honoured on every supported NestJS version β\nthe collecting is implemented by this library, and the installed `ConsoleLogger`\nonly decides the default of `structuredParams`. That also lets you switch to the\nNestJS 12 output while still on NestJS 11, so upgrading NestJS later does not\nchange your logs.\n\nA flattened param named `context` or `stack` is used as such when the call does\nnot set them itself, and loses to the explicit form when it does β so\n`log('msg', { context: 'A' })` logs the context `A`, while\n`log('msg', { context: 'A' }, 'B')` logs `B`.\n\nCollisions with the fields pino adds β the level, the timestamp, the message\nkey, the base bindings β are not resolved at all: pino does not deduplicate keys\neither, and their names depend on your pino options, so naming a param `level`\nis your call to make.\n\nOutput:\n\n```json\n// Logs by app itself\n{\"level\":30,\"time\":1629823318326,\"pid\":14727,\"hostname\":\"my-host\",\"context\":\"NestFactory\",\"msg\":\"Starting Nest application...\"}\n{\"level\":30,\"time\":1629823318326,\"pid\":14727,\"hostname\":\"my-host\",\"context\":\"InstanceLoader\",\"msg\":\"LoggerModule dependencies initialized\"}\n{\"level\":30,\"time\":1629823318327,\"pid\":14727,\"hostname\":\"my-host\",\"context\":\"InstanceLoader\",\"msg\":\"AppModule dependencies initialized\"}\n{\"level\":30,\"time\":1629823318327,\"pid\":14727,\"hostname\":\"my-host\",\"context\":\"RoutesResolver\",\"msg\":\"AppController {/}:\"}\n{\"level\":30,\"time\":1629823318327,\"pid\":14727,\"hostname\":\"my-host\",\"context\":\"RouterExplorer\",\"msg\":\"Mapped {/, GET} route\"}\n{\"level\":30,\"time\":1629823318327,\"pid\":14727,\"hostname\":\"my-host\",\"context\":\"NestApplication\",\"msg\":\"Nest application successfully started\"}\n\n// Logs by injected Logger and PinoLogger in Services/Controllers. Every log\n// has it's request data and unique `req.id` (by default id is unique per\n// process, but you can set function to generate it from request context and\n// for example pass here incoming `X-Request-ID` header or generate UUID)\n{\"level\":10,\"time\":1629823792023,\"pid\":15067,\"hostname\":\"my-host\",\"req\":{\"id\":1,\"method\":\"GET\",\"url\":\"/\",\"query\":{},\"params\":{\"0\":\"\"},\"headers\":{\"host\":\"localhost:3000\",\"user-agent\":\"curl/7.64.1\",\"accept\":\"*/*\"},\"remoteAddress\":\"::1\",\"remotePort\":63822},\"context\":\"MyService\",\"foo\":\"bar\",\"msg\":\"baz qux\"}\n{\"level\":20,\"time\":1629823792023,\"pid\":15067,\"hostname\":\"my-host\",\"req\":{\"id\":1,\"method\":\"GET\",\"url\":\"/\",\"query\":{},\"params\":{\"0\":\"\"},\"headers\":{\"host\":\"localhost:3000\",\"user-agent\":\"curl/7.64.1\",\"accept\":\"*/*\"},\"remoteAddress\":\"::1\",\"remotePort\":63822},\"context\":\"MyService\",\"msg\":\"foo bar {\\\"baz\\\":\\\"qux\\\"}\"}\n{\"level\":30,\"time\":1629823792023,\"pid\":15067,\"hostname\":\"my-host\",\"req\":{\"id\":1,\"method\":\"GET\",\"url\":\"/\",\"query\":{},\"params\":{\"0\":\"\"},\"headers\":{\"host\":\"localhost:3000\",\"user-agent\":\"curl/7.64.1\",\"accept\":\"*/*\"},\"remoteAddress\":\"::1\",\"remotePort\":63822},\"context\":\"MyService\",\"msg\":\"foo\"}\n\n// Automatic logs of every request/response\n{\"level\":30,\"time\":1629823792029,\"pid\":15067,\"hostname\":\"my-host\",\"req\":{\"id\":1,\"method\":\"GET\",\"url\":\"/\",\"query\":{},\"params\":{\"0\":\"\"},\"headers\":{\"host\":\"localhost:3000\",\"user-agent\":\"curl/7.64.1\",\"accept\":\"*/*\"},\"remoteAddress\":\"::1\",\"remotePort\":63822},\"res\":{\"statusCode\":200,\"headers\":{\"x-powered-by\":\"Express\",\"content-type\":\"text/html; charset=utf-8\",\"content-length\":\"12\",\"etag\":\"W/\\\"c-Lve95gjOVATpfV8EL5X4nxwjKHE\\\"\"}},\"responseTime\":7,\"msg\":\"request completed\"}\n```\n\n## Comparison with others\n\nThere are other Nestjs loggers. Key purposes of this module are:\n\n- to be idiomatic NestJS logger\n- to log in JSON format (thanks to [pino](https://getpino.io/#/) - [super fast logger](https://github.com/pinojs/pino/blob/master/docs/benchmarks.md)) [why](https://www.loggly.com/use-cases/json-logging-best-practices/) [you](https://hackernoon.com/log-everything-as-json-hmq32ax) [should](https://blog.treasuredata.com/blog/2012/04/26/log-everything-as-json/) [use](https://stackify.com/what-is-structured-logging-and-why-developers-need-it/) [JSON](https://softwareengineering.stackexchange.com/a/170528)\n- to log every request/response automatically (thanks to [pino-http](https://github.com/pinojs/pino-http#pino-http))\n- to bind request data to the logs automatically from any service on any application layer without passing request context (thanks to [AsyncLocalStorage](https://nodejs.org/api/async_context.html#async_context_class_asynclocalstorage))\n- to have another alternative logger with same API as `pino` instance (`PinoLogger`) for experienced `pino` users to make more comfortable usage.\n\n| Logger | Nest App logger | Logger service | Auto-bind request data to logs |\n| ------------------ | :-------------: | :------------: | :---------------------------: |\n| nest-winston | + | + | - |\n| nestjs-pino-logger | + | + | - |\n| **nestjs-pino** | + | + | + |\n\n## Configuration\n\n### Zero configuration\n\nJust import `LoggerModule` to your module:\n\n```ts\nimport { LoggerModule } from 'nestjs-pino';\n\n@Module({\n imports: [LoggerModule.forRoot()],\n ...\n})\nclass MyModule {}\n```\n\n### Configuration params\n\nThe following interface is using for the configuration:\n\n```ts\ninterface Params<\n IM = IncomingMessage,\n SR = ServerResponse,\n CustomLevels extends string = never,\n> {\n /**\n * Optional parameters for `pino-http` module\n * @see https://github.com/pinojs/pino-http#api\n */\n pinoHttp?:\n | pinoHttp.Options