@tresdoce-nestjs-toolkit/tracing NPM

⚠️ Es importante tener en cuenta que este interceptor se encuentra implementado en el package @tresdoce-nestjs-toolkit/paas, ya que es una funcionalidad core para el starter.

Este módulo está pensado para ser utilizado en NestJS Starter, o cualquier proyecto que utilice una configuración centralizada, siguiendo la misma arquitectura del starter.

Glosario

📝 Requerimientos básicos

NestJS Starter
Node.js v20.18.0 or higher (Download)
YARN v1.22.19 or higher
NPM v10.9.0 or higher
NestJS v10.4.7 or higher (Documentación)

🛠️ Instalar dependencia

npm install -S @tresdoce-nestjs-toolkit/tracing

yarn add @tresdoce-nestjs-toolkit/tracing

⚙️ Configuración

//./src/config/configuration.ts
import { Typings } from '@tresdoce-nestjs-toolkit/core';
import { registerAs } from '@nestjs/config';
import * as PACKAGE_JSON from '../../package.json';

export default registerAs('config', (): Typings.AppConfig => {
  return {
    //...
    tracing: {
      resourceAttributes: {
        serviceName: `${PACKAGE_JSON.name}`,
        version: PACKAGE_JSON.version,
        'service.namespace': `${process.env.API_PREFIX}`,
        'deployment.environment': process.env.APP_STAGE,
      },
      exporter: {
        url: process.env.TRACING_ENDPOINT,
        /*headers: {
          Authorization: '<token>',
        },*/
      },
      //ignorePaths: process.env.TRACING_IGNORE_PATHS ? process.env.TRACING_IGNORE_PATHS.split(',') : [],
    },
    //...
  };
});

resourceAttributes: Tags para la traza que se ingresa como objeto con KEY:VALUE, puedes ver que valores admite revisando la documentación de Semantic Conventions

Type: Object
Default: { 'serviceName': options.serviceName }

resourceAttributes.serviceName: Es el nombre de la aplicación para la traza

Type: String

resourceAttributes.version: Es la version de la aplicación para la traza

Type: String

resourceAttributes.service.namespace: Es un nombre para agrupar la traza por grupos

Type: String

resourceAttributes.deployment.environment: Es el entorno en el que está desplegado la aplicación

Type: String

exporter: Es la configuración del exportador de la traza y sus valores se definen como KEY:VALUE, puedes ver que valores admite revisando la documentación de OTLP Exporter Configuration

Type: Object
Default: { 'url': 'http://localhost:4318/v1/traces' }
Example: 'http://localhost:4318/v1/traces' | 'http://docker:4318/v1/traces' | 'https://otelcol.aspecto.io/v1/trace'

exporter.url: Es la url del endpoint que va a estar colectando la traza.

Type: String

exporter.headers: Es la configuración de los headers del colector de la traza.

Type: Object
Example: { Authorization: '<aspecto-io-token>' }

ignorePaths: Es una configuración opcional para excluir la traza por medio de los paths. Esta configuración es un array de strings, donde los valores se escriben en formato globs y se suman a los excludes por defecto.

Type: Array
Default: ['**/health/liveness', '**/health/readiness', '**/info', '**/metrics', '**/docs', '**/docs/*', '**/docs/**']
Example: ['**/users/*', '**/test-env']

👨‍💻 Uso

Inicializamos Opentelemetry previo a inicializar la app, pasando los datos de la config.

//./src/main.ts
import { otelProvider } from '@tresdoce-nestjs-toolkit/tracing';
import { config } from './config';

async function bootstrap() {
  await otelProvider(config().tracing);
  //...
}

(async () => await bootstrap())();

Instanciar el TracingModule y el TracingInterceptor para que empiece a realizar la traza de la app.

//./src/app.module.ts
import { APP_INTERCEPTOR } from '@nestjs/core';
import { TracingModule, TracingInterceptor } from '@tresdoce-nestjs-toolkit/tracing';

@Module({
  imports: [
    //...
    TracingModule,
    //...
  ],
  //...
  providers: [
    AppService,
    {
      provide: APP_INTERCEPTOR,
      useClass: TracingInterceptor,
    },
    //...
  ],
})
export class AppModule {}

Excluir paths para la traza

//./src/app.controller.ts
import { Controller, Get } from '@nestjs/common';
import { SkipTrace } from '@tresdoce-nestjs-toolkit/tracing';

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  async getHello(): Promise<string> {
    return 'hello world!';
  }

  @SkipTrace() // use this decorator to skip trace
  @Get('my-util')
  getMyUtil() {
    return 'my util';
  }
}