@xtreamsrl/nest-logging

This package exports a NestJS dyn-module LoggingModule, a ConsoleLogger and TestLogger adapters and a LoggerServicePort.

LoggingModule

The LoggingModule is a dynamic NestJS module which makes it easy to configure and use a logging system in your NestJS applications.

It registers a global LoggerService provider to the app DI container. The LoggerService can be used to provide a consistent logging mechanism across the entire application, allowing developers to easily track and debug application behavior.

LoggerServicePort

Ports are interfaces that define contracts that should be implemented by adapters, to abstract technical details. In this case, the LoggerServicePort defines the service interface that provides logging functionality.

ConsoleLogger

The ConsoleLogger adapter provides an easy way to output logs to the console and provide an example on how to create a LoggerPort adapter.

TestLogger

The TestLogger adapter provides a dummy logger that can be mocked in unit tests to verify that the correct logs are being emitted, if needed.

Installation

npm install @xtreamsrl/nest-logging

Usage

In your application module, import the LoggingModule as follows and configure it appropriately :

import { ConsoleLogger, LoggingModule } from '@xtreamsrl/nest-logging';

@Module({
  imports: [
    LoggingModule.forRoot({
      context: 'root',
      global: true,
      loggerAdapter: {
        useClass: ConsoleLogger,
      },
      enableTracingIntegration: false,
      enableLoggerInterceptor: false,
    })
  ],
  controllers: [],
  providers: [],
})
export class AppModule {}

Nest App Logger

To instruct Nest to use an instance of the LoggerService as the app logger, the LoggerService must be configured using the app.useLogger() method. This can be done along with app bootstrap, as follows:

  import { LoggerServicePort } from '@xtreamsrl/nest-logging';
  const app = await NestFactory.create(AppModule, {
    bufferLogs: true,
  });
  app.useLogger(await app.resolve<LoggerServicePort>(LoggerServicePort));
  app.flushLogs();

Context overriding

To have better contextualized log messages, it is recommended to override the context of the LoggerService when it is injected in the constructor:

@Injectable()
export class ExampleService {
  constructor(private readonly logger: LoggerServicePort) {
    this.logger.setContext(ExampleService.name);
  }
}

Configuration

global

Determines if the module is registered global-scoped or not. When true, makes the LoggingModule module global-scoped. Once imported into any module, a global-scoped module will be visible in all modules. Thereafter, modules that wish to inject a service exported from a global module do not need to import the provider module.

loggerAdapter

A NestJS valid provider (ClassProvider, ValueProvider, FactoryProvider, ExistingProvider), excluded the provide property, of a LoggerPort adapter.

enableTracingIntegration

A boolean flag to indicate whether the tracing integration with OpenTelemetry should be enabled. If true, data from the active span context are retrieved and propagated to the LoggerAdapter through the DiagnosticContext.

spanAttributes

Optional list of attributes of the span to retrieve and include in the logging DiagnosticContext.

envsVar

Optional list of environment variables to retrieve and include in the logging DiagnosticContext.

context

The context that the logger will be associated with. Can and should be overwritten where the LoggerService is used.

enableLoggerInterceptor

A boolean flag to indicate whether the LoggerInterceptor should be enabled. When enabled, the LoggerInterceptor is registered as a global app interceptor.

requestMapper

A function used to extract request information from the execution context and map into a RequestInfo object. This mapping function is needed to keep the LoggerInterceptor agnostic from the web framework used in the app (Fastify, Express).Required if logger interceptor is enabled. Required if logger interceptor is enabled.

responseMapper

A function used to extract response information from the execution context and map into a ResponseInfo object. This mapping function is needed to keep the LoggerInterceptor agnostic from the web framework used in the app (Fastify, Express). Required if logger interceptor is enabled.

excludeRoutes

Optional array of strings that represent routes to be excluded from logging by the LoggerInterceptor.

DiagnosticContext

The DiagnosticContext (freely inspired by Spring MDC) offers a method to enhance log messages with additional information which can greatly improve the tracking of the program's execution. Among these, can be added to the DiagnosticContext :

• Runtime environment variables values.
• OpenTelemetry tracing information, such as active spanId and traceId, if any.
• Application labels provided by the developer for each specific case.

Build

Run nx build nest-logging to build the package.

Run unit tests

Run nx test nest-logging to execute the unit tests via Jest.

Versioning

Export the GH_TOKEN environment variable with your GitHub token with at least the repo scope:

export GH_TOKEN=<YOUR_PERSONAL_GH_TOKEN>

Then run the following command:

lerna version

The GH_TOKEN is needed to push the version commit and tag to the remote repository and to create the release on GitHub.

For general information about the versioning process, please refer to the root Readme Versioning section.

Publishing

Update your local .npmrc file to include the following lines:

@xtreamsrl:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

The ${NPM_TOKEN} placeholder is a npm personal access token publish permissions on the @xtreamsrl organization. It can be treated as placeholder to replace with the actual token value, or you can set it as an environment variable:

export NPM_TOKEN=<YOUR_PERSONAL_NPM_TOKEN>

Then run the following command:

npm run lerna-publish

Who we are