README.md

NestJS OpenTelemetry

This library provides deeply integrated protocol-agnostic Nestjs OpenTelemetry instrumentations, metrics and SDK.

Description

Nestjs is a protocol-agnostic framework. That's why this library can able to work with different protocols like RabbitMQ, GRPC and HTTP. Also you can observe and trace Nestjs specific layers like Pipe, Guard, Controller and Provider.

It also includes auto trace and metric instrumentations for some popular Nestjs libraries.

• Distributed Tracing

  • Setup
  • Decorators
  • Trace Providers
  • Auto Trace Instrumentations

OpenTelemetry Metrics currently experimental. So, this library doesn't support metric decorators and Auto Observers until it's stable. but if you want to use it, you can use OpenTelemetry API directly.

Only supports NestJS 9.x

Installation

npm install @easyv/nestjs-opentelemetry --save

---

Configuration

This is a basic configuration without any trace and metric exporter, but includes default metrics and injectors

import { OpenTelemetryModule } from '@easyv/nestjs-opentelemetry'

@Module({
  imports: [
    OpenTelemetryModule.forRoot({
      serviceName: 'nestjs-opentelemetry-example',
    })
  ]
})
export class AppModule {}

Async configuration example (Not recommended, May cause auto instrumentations to not work)

import { OpenTelemetryModule } from '@easyv/nestjs-opentelemetry'
import { ConfigModule, ConfigService } from '@nestjs/config'

@Module({
  imports: [
    OpenTelemetryModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: async (configService: ConfigService) => ({
        serviceName: configService.get('SERVICE_NAME'),
      }),
      inject: [ConfigService]
    })
  ]
})
export class AppModule {}

Default Parameters

key	value	description
traceInjectors	DecoratorInjector, ScheduleInjector, ControllerInjector, GuardInjector, PipeInjector, InterceptorInjector, ExceptionFilterInjector, TypeormInjector, LoggerInjector, ProviderInjector, MiddlewareInjector	default auto trace instrumentations
contextManager	AsyncLocalStorageContextManager	default trace context manager inherited from NodeSDKConfiguration
instrumentations	AutoInstrumentations	default instrumentations inherited from NodeSDKConfiguration
textMapPropagator	W3CTraceContextPropagator	default textMapPropagator inherited from NodeSDKConfiguration

OpenTelemetryModule.forRoot() takes OpenTelemetryModuleConfig as a parameter, this type is inherited by NodeSDKConfiguration so you can use same OpenTelemetry SDK parameter.

---

Distributed Tracing

Simple setup with Zipkin exporter, including with default trace instrumentations.

import { OpenTelemetryModule } from '@easyv/nestjs-opentelemetry'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc'
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base'

@Module({
  imports: [
    OpenTelemetryModule.forRoot({
      spanProcessor: new SimpleSpanProcessor(
        new OTLPTraceExporter({
          url: 'http://<collector-hostname>:<port>',
        })
      ),
    }),
  ],
})
export class AppModule {}

After setup, your application will be instrumented, so that you can see almost every layer of application in ZipkinUI, including Guards, Pipes, Controllers even global layers like this

List of supported official exporters here.

---

Trace Decorators

This library supports auto instrumentations for Nestjs layers, but sometimes you need to define custom span for specific method blocks like providers methods. In this case @Trace and @TracePlain decorator will help you.

import { Injectable } from '@nestjs/common'
import { Trace } from '@easyv/nestjs-opentelemetry'

@Injectable()
export class AppService {
  @Trace()
  getHello(): string {
    return 'Hello World!'
  }
}

Also @Trace decorator takes name field as a parameter

@Trace({ name: 'hello' })

---

Trace Providers

In an advanced usage case, you need to access the native OpenTelemetry Trace provider to access them from Nestjs application context.

import { Injectable } from '@nestjs/common'
import { Tracer } from '@opentelemetry/sdk-trace-base'

@Injectable()
export class AppService {
  constructor() {}

  getHello(): string {
    const span = trace.getTracer('default').startSpan('important_section_start')
    // do something important
    span.setAttributes({ userId: 1150 })
    span.end()
    return 'Hello World!'
  }
}

---

Auto Trace Instrumentations

The most helpful part of this library is that you already get all of the instrumentations by default if you set up a module without any extra configuration. If you need to avoid some of them, you can use the traceAutoInjectors parameter.

import { Module } from '@nestjs/common'
import {
  ControllerInjector,
  EventEmitterInjector,
  GuardInjector,
  LoggerInjector,
  OpenTelemetryModule,
  PipeInjector,
  ScheduleInjector,
} from '@easyv/nestjs-opentelemetry'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc'
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base'

@Module({
  imports: [
    OpenTelemetryModule.forRoot({
      traceInjectors: [
        ControllerInjector,
        GuardInjector,
        EventEmitterInjector,
        ScheduleInjector,
        PipeInjector,
        LoggerInjector,
      ],
      spanProcessor: new SimpleSpanProcessor(
        new OTLPTraceExporter({
          url: 'http://<collector-hostname>:<port>',
        })
      ),
    }),
  ]
})
export class AppModule {}

List of Trace Injectors

Instance	Description
ControllerInjector	Auto trace all of module controllers
DecoratorInjector	Auto trace all of decorator providers
GuardInjector	Auto trace all of module guards including global guards
PipeInjector	Auto trace all of module pipes including global pipes
InterceptorInjector	Auto trace all of module interceptors including global interceptors
ExceptionFilterInjector	Auto trace all of module exceptionFilters including global exceptionFilters
MiddlewareInjector	Auto trace all of module middlewares including global middlewares
ProviderInjector	Auto trace all of module providers
ScheduleInjector	Auto trace for @nestjs/schedule library, supports all features
LoggerInjector	Logger class tracer
TypeormInjector	Auto trace for typeorm library

---