NestJS Pino module

A NestJS module for integrating the Pino logger into your NestJS applications.

Table of Contents

• Installation
• Overview
• Environment Variables
• Usage
  • Basic Setup
  • Configuration Options
  • Async Configuration
• Log Output Examples
  • JSON Format
  • Plain Text Format
  • With Call Sites
• Advanced Usage with Direct Pino Access
• Integration with NestJS
• Integration with TypeORM
• License

Installation

1npm install @toxicoder/nestjs-pino

Overview

This module provides a seamless integration of the Pino logger into NestJS applications. Pino is one of the fastest JSON loggers available for Node.js, offering:

• High Performance: Extremely fast logging with minimal overhead
• Structured Logging: JSON output by default for better log processing
• Low Overhead: Minimal impact on your application's performance
• Flexible Configuration: Extensive options for customizing log output
• Pretty Printing: Human-readable logs during development

The module includes:

• NestJS-compatible logger service
• Environment variable configuration
• Support for call site tracking
• Flexible formatting options
• TypeORM logger compatibility

Environment Variables

Variable	Type	Default	Description
LOG_LEVEL	string	'info'	Sets the minimum log level ('fatal', 'error', 'warn', 'info', 'debug', 'trace')
LOG_JSON	boolean	true	Whether to output logs in JSON format
LOG_PRETTY	boolean	undefined	Whether to use pretty formatting for logs (only applies when LOG_JSON is false)
LOG_COLOR	boolean	undefined	Whether to colorize log output (only applies when LOG_JSON is false)
LOG_CALLSITES	boolean	false	Whether to include call sites in logs
LOG_DB	string/boolean	undefined	Controls TypeORM logging. Can be a log level or boolean to enable/disable

Usage

Basic Setup

The simplest way to use the module is with the default configuration:

1import { Module } from '@nestjs/common';
2import { PinoModule } from '@toxicoder/nestjs-pino';
3
4@Module({
5  imports: [PinoModule],
6})
7export class AppModule {}

Configuration Options

You can customize the logger using the forRoot method:

1import { Module } from '@nestjs/common';
2import { PinoModule } from '@toxicoder/nestjs-pino';
3
4@Module({
5  imports: [
6    PinoModule.forRoot({
7      level: 'debug',
8      callsites: true,
9      json: false,
10      pretty: true,
11      color: true,
12    }),
13  ],
14})
15export class AppModule {}

Async Configuration

For dynamic configuration, use the forRootAsync method:

1import { PinoModule, PinoOptions } from '@toxicoder/nestjs-pino';
2import { ClsModule, ClsService } from 'nestjs-cls';
3
4import { ConfigModule, LoggerConfig } from '~config';
5
6@Module({
7  imports: [
8    ClsModule.forRoot({
9      global: true,
10      middleware: {
11        mount: true,
12        generateId: true,
13        idGenerator: uuid,
14      },
15    }),
16    PinoModule.forRootAsync({
17      imports: [ConfigModule],
18      inject: [LoggerConfig, ClsService],
19      useFactory: (config: LoggerConfig, cls: ClsService) => ({
20        ...config.getConfig(),
21        relativeTo: path.resolve(process.cwd()),
22        stackAdjustment: 2,
23        mixin: () => ({
24          traceId: cls.getId(),
25        }),
26      }),
27    }),
28  ],
29})
30export class AppModule {}

Log Output Examples

JSON Format

When LOG_JSON=true (default), logs are output in JSON format:

1{"level":"info","time":"2023-11-15T12:34:56.789Z","message":"Application started"}
2{"level":"error","time":"2023-11-15T12:35:01.234Z","message":"Failed to connect to database","error":"Connection refused"}

Plain Text Format

When LOG_JSON=false and LOG_PRETTY=true, logs are formatted for human readability:

[12:34:56.789] INFO: Application started
[12:35:01.234] ERROR: Failed to connect to database
    error: Connection refused

With Call Sites

When LOG_CALLSITES=true, logs include the file and line where the log was called:

1{
2  "level": "info",
3  "time": "2023-11-15T12:34:56.789Z",
4  "message": "Application started",
5  "caller": "src/main.ts:15"
6}

Or in pretty format:

[12:34:56.789] INFO (src/main.ts:15): Application started

Advanced Usage with Direct Pino Access

The pino instance in PinoService is publicly accessible, allowing you to use all native Pino features directly:

1import { Injectable } from '@nestjs/common';
2import { PinoService } from '@toxicoder/nestjs-pino';
3
4@Injectable()
5export class MonitoringService {
6  private logger;
7
8  constructor(private readonly pinoService: PinoService) {
9    this.logger = this.pinoService.pino.child(
10      {
11        context: 'MonitoringService',
12      },
13      {
14        customLevels: {
15          critical: 60,
16          security: 55,
17          business: 35,
18        },
19      },
20    );
21  }
22
23  monitorSystem() {
24    // Use standard levels
25    this.logger.info('System check started');
26
27    // Use custom levels
28    this.logger.business('Business event occurred');
29    this.logger.security('Security event detected');
30    this.logger.critical('Critical system failure');
31  }
32}

Integration with NestJS

To use the logger in your NestJS application's main.ts file:

1import { NestFactory } from '@nestjs/core';
2import { PinoService } from '@toxicoder/nestjs-pino';
3
4import { AppModule } from './app.module';
5
6async function bootstrap() {
7  const app = await NestFactory.create(AppModule, {
8    bufferLogs: true, // Buffer logs until logger is available
9  });
10
11  // Get the PinoService from the application context
12  const logger = app.get(PinoService);
13
14  // Set the logger as the application logger
15  app.useLogger(logger);
16
17  await app.listen(3000);
18
19  logger.log(`Application is running on: ${await app.getUrl()}`);
20}
21
22bootstrap();

This setup ensures that all NestJS internal logs (from controllers, services, etc.) will be processed through Pino.

Integration with TypeORM

The PinoService implements TypeORM's logger interface, allowing it to be used directly as a TypeORM logger.

Configuration

You can enable TypeORM logging by setting the LOG_DB environment variable or by configuring the dbLogging option:

1import { Module } from '@nestjs/common';
2import { TypeOrmModule } from '@nestjs/typeorm';
3import { PinoModule, PinoService } from '@toxicoder/nestjs-pino';
4
5@Module({
6  imports: [
7    PinoModule.forRoot({
8      dbLogging: 'debug', // or true to use the same level as the main logger
9    }),
10    TypeOrmModule.forRootAsync({
11      imports: [PinoModule],
12      inject: [PinoService],
13      useFactory: (logger: PinoService) => ({
14        type: 'postgres',
15        host: 'localhost',
16        port: 5432,
17        username: 'postgres',
18        password: 'postgres',
19        database: 'test',
20        entities: [],
21        logger, // Use PinoService as TypeORM logger
22      }),
23    }),
24  ],
25})
26export class AppModule {}

Log Levels

The TypeORM logger uses the following Pino log levels:

• info: Migration and schema build logs
• debug: Query logs
• warn: Slow query logs
• error: Query error logs

Example Output

JSON format:

1{"level":"debug","time":"2023-11-15T12:34:56.789Z","context":"typeorm","message":"QUERY: SELECT * FROM users WHERE id = $1 [1]"}
2{"level":"error","time":"2023-11-15T12:35:01.234Z","context":"typeorm","message":"ERROR: connection refused\nquery: SELECT * FROM users\nparameters: []"}

Pretty format:

[12:34:56.789] DEBUG (typeorm): QUERY: SELECT * FROM users WHERE id = $1 [1]
[12:35:01.234] ERROR (typeorm): ERROR: connection refused
    query: SELECT * FROM users
    parameters: []

License

This project is licensed under the ISC License - see the package.json file for details.