Overview

@josemarinho/nestjs-kibana-logger is a flexible logging module for NestJS that leverages Pino and integrates with:

• Elasticsearch/Kibana using pino-elasticsearch
• Local file logging
• Request context tracing via nestjs-cls
• Custom trace ID injection
• Full compatibility with the built-in NestJS Logger

Installation

# with npm
$ npm install @josemarinho/nestjs-kibana-logger
# with yarn
$ yarn add @josemarinho/nestjs-kibana-logger
# with pnpm
$ pnpm add @josemarinho/nestjs-kibana-logger

Running the app

Once the installation process is complete, we can import the LogModule into the root AppModule.

import { Module } from '@nestjs/common';
import { LogModule } from '@josemarinho/nestjs-kibana-logger';

@Module({
  imports: [
    LogModule.forRoot({
      kibanaHost: 'elasticsearch-host',
      indexKibana: 'index-kibana'
    }),
  ],
  ...
})
export class AppModule {}

Adding Custom Log Metadata (base)

You can optionally pass a base object inside your LogModule.forRoot configuration. The base properties will be automatically added to all log entries.

This is useful for adding fixed metadata such as environment, application name, team name, etc.

LogModule.forRoot({
  kibanaHost: 'elasticsearch-host',
  indexKibana: 'index-kibana',
  base: {
    app: 'my-app',
    env: 'production',
    team: 'squad-alpha',
  },
});

Each log will now include this metadata automatically:

{
  "level": 30,
  "time": "...",
  "msg": "your log message",
  "app": "locket-letter-api",
  "env": "production",
  "team": "squad-alpha"
}

Note: You are free to customize the fields included in the base object according to your needs. These values are static and applied to all logs globally.

If you use Basic Authentication with username and password or with ApiKey, you can add it to the configuration.

Only use one or the other authentication

import { Module } from '@nestjs/common';
import { LogModule } from '@josemarinho/nestjs-kibana-logger';

@Module({
  imports: [
    LogModule.forRoot({
      kibanaHost: 'elasticsearch-host',
      indexKibana: 'index-kibana',
      auth: {
        username: 'elasticsearch-user',
        password: 'elasticsearch-password',
        apiKey: 'api-key'
      },
    }),
  ],
  ...
})
export class AppModule {}

🧵 Request Trace ID Propagation

This solution uses ClsModule to generate a unique traceId for each request, ensuring consistent tracing throughout the application. The TraceIdMiddleware checks for the x-trace-id header or generates a new traceId and stores it in the context. The custom LogService retrieves this traceId from the context and includes it in all log messages for better traceability.

LogModule.forRoot({
  // rest of configuration
  traceIdHeaderName: 'header-name' // by default is 'x-trace-id'
})

Integrating the Log Service in main.ts

To utilize the custom logging functionality provided by your library, the Log service is set as the logger for the NestJS application. Here’s a breakdown:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { LogService } from '@josemarinho/nestjs-kibana-logger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, { bufferLogs: true });
  app.useLogger(app.get(LogService));
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

Utilization

The AppService class demonstrates how to use the built-in Logger from NestJS for logging.

import { Injectable, Logger } from '@nestjs/common';

@Injectable()
export class AppService {
  private readonly logger = new Logger(AppService.name);

  doSomething(): void {  
    this.logger.log('This is a log message');      // Standard log message  
    this.logger.warn('This is a warning message'); // Warning message  
    this.logger.error('This is an error message'); // Error message  
  }  
}

🔍 Elasticsearch Health Check (com Terminus)

If you’re using @nestjs/terminus, you can integrate a health indicator for your Elasticsearch/Kibana service using the same configuration.

Just import class ElasticsearchHealthIndicator inside your HealthCheckController. Like this:

import { Controller, Get } from '@nestjs/common';
import {
  HealthCheck,
  HealthCheckService,
} from '@nestjs/terminus';
import { ElasticsearchHealthIndicator } from "@josemarinho/nestjs-kibana-logger";

@Controller('health')
export class HealthController {
  constructor(
    private readonly health: HealthCheckService,
    private readonly elasticsearch: ElasticsearchHealthIndicator,
  ) {}

  @Get()
  @HealthCheck()
  check() {
    return this.health.check([
      () => this.elasticsearch.pingCheck('elasticsearch'),
    ]);
  }
}

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

After your app it's ready to running.

🙏 Acknowledgments

This module was made possible thanks to the following open source projects and libraries:

• NestJS — A progressive Node.js framework for building efficient, scalable server-side applications.
• Pino — The fastest Node.js logger, and the foundation of structured logging in this module.
• pino-elasticsearch — A powerful transport for streaming logs directly to Elasticsearch.
• nestjs-cls — Contextual request tracing for NestJS via AsyncLocalStorage.
• @nestjs/terminus — Health checks for microservices and backend systems.
• The open source community — For continuous inspiration and contributions that make projects like this possible.

Special thanks to the contributors of these projects.