2. Import the metric file and start otel node SDK:

import otelSDK from './tracing';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { Logger } from 'nestjs-pino';

async function bootstrap() {
  // Start SDK before nestjs factory create
  await otelSDK.start();

  const app = await NestFactory.create(AppModule);
  app.useLogger(app.get(Logger));
  await app.listen(3000);
}
bootstrap();

3. Configure nest-otel:

3.1. With forRoot:

const OpenTelemetryModuleConfig = OpenTelemetryModule.forRoot({
  metrics: {
    hostMetrics: true, // Includes Host Metrics
  },
});

@Module({
  imports: [OpenTelemetryModuleConfig],
})
export class AppModule {}

3.2. With forRootAsync:

OpenTelemetryModule.forRootAsync({
  useClass: OtelConfigService
});

import { Injectable, Logger } from '@nestjs/common'
import { ConfigService } from '@nestjs/config'
import { OpenTelemetryOptionsFactory, OpenTelemetryModuleOptions } from 'nestjs-otel';

@Injectable()
export class OtelConfigService implements OpenTelemetryOptionsFactory {
  private readonly logger = new Logger(OtelConfigService.name)

  constructor(private configService: ConfigService) {}

  createOpenTelemetryOptions(): Promise<OpenTelemetryModuleOptions> | OpenTelemetryModuleOptions {
    const { hostMetrics } = this.configService.get('otel')

    return {
      metrics: {
        hostMetrics: hostMetrics.enabled,
      },
    };
  }
}

Span Decorator

If you need, you can define a custom Tracing Span for a method. It works async or sync.

Span optionally takes one or both of the following parameters:

• name - explicit name of the span; if omitted, it is derived as <class-name>.<method-name>.
• options - SpanOptions to customize the span options.

You can also supply a function as the options argument. It will be called with the decorated method's arguments, so you can dynamically customize the span options.

import { Span } from 'nestjs-otel';

export class BooksService {

  // span.name == 'CRITICAL_SECTION'
  @Span('CRITICAL_SECTION')
  async getBooks() {
      return [`Harry Potter and the Philosopher's Stone`];
  }

  // span.name == 'BooksService.getBooksAgain'
  @Span()
  async getBooksAgain() {
      return [`Harry Potter and the Philosopher's Stone`];
  }

  // explicitly set span options
  @Span('getBook', { kind: SpanKind.SERVER })
  async getBook(id: number) {
    // ...
  }

  // options are set dynamically based on the id parameter
  @Span('getBook', (id) => ({ attributes: { bookId: id } }))
  async getBookAgain(id: number) {
    // ...
  }

  // same as above, but span name is omitted and inferred automatically
  @Span((id) => ({ attributes: { bookId: id } }))
  async getBookOnceMore(id: number) {
    // ...
  }

  // Capture return value as attribute
  // Note: Explicitly type the result to ensure type safety
  @Span({
    onResult: (result: string[]) => ({ attributes: { 'book.count': result.length } }),
  })
  async getBooks() {
    return ['Book 1', 'Book 2'];
  }
}

Traceable Decorator

If you want to trace all methods in a class, you can use the @Traceable decorator.

import { Traceable } from 'nestjs-otel';

@Injectable()
@Traceable()
export class UsersService {
  findAll() {
    // This method will be automatically traced
    return [];
  }

  findOne(id: string) {
    // This method will also be automatically traced
    return {};
  }
}

Current Span Decorator

You can access the current span in your controllers using the @CurrentSpan decorator.

Note: This decorator only works in Controllers, Resolvers, and Gateways where NestJS handles argument injection. It does not work in standard service-to-service calls.

import { Controller, Get } from '@nestjs/common';
import { Span } from '@opentelemetry/api';
import { CurrentSpan } from 'nestjs-otel';

@Controller('cats')
export class CatsController {
  @Get()
  findAll(@CurrentSpan() span: Span) {
    if (span) {
      span.setAttribute('custom.attribute', 'value');
    }
    return 'This action returns all cats';
  }
}

Baggage Decorator

You can access the OpenTelemetry Baggage (Distributed Context) in your controllers using the @Baggage decorator.

import { Controller, Get } from '@nestjs/common';
import { Baggage } from 'nestjs-otel';

@Controller('cats')
export class CatsController {
  @Get()
  findAll(@Baggage('tenant-id') tenantId: string) {
    console.log('Tenant ID:', tenantId);
    return 'This action returns all cats';
  }
}

Tracing Service

In case you need to access native span methods for special logics in the method block:

import { TraceService } from 'nestjs-otel';

@Injectable()
export class BookService {
  constructor(private readonly traceService: TraceService) {}

  @Span()
  async getBooks() {
    const currentSpan = this.traceService.getSpan(); // --> retrives current span, comes from http or @Span
    await this.doSomething();
    currentSpan.addEvent('event 1');
    currentSpan.end(); // current span end

    const span = this.traceService.startSpan('sub_span'); // start new span
    span.setAttributes({ userId: 1 });
    await this.doSomethingElse();
    span.end(); // new span ends
    return [`Harry Potter and the Philosopher's Stone`];
  }
}

Metric Service

OpenTelemetry Metrics allow a user to collect data and export it to metrics backend like Prometheus.

import { MetricService } from 'nestjs-otel';
import { Counter } from '@opentelemetry/api';

@Injectable()
export class BookService {
  private customMetricCounter: Counter;

  constructor(private readonly metricService: MetricService) {
    this.customMetricCounter = this.metricService.getCounter('custom_counter', {
      description: 'Description for counter',
    });
  }

  async getBooks() {
    this.customMetricCounter.add(1);
    return [`Harry Potter and the Philosopher's Stone`];
  }
}

Metric Decorators

Metric Class Instances

If you want to count how many instance of a specific class has been created:

@OtelInstanceCounter() // It will generate a counter called: app_MyClass_instances_total.
export class MyClass {}

Metric Class Method

If you want to increment a counter on each call of a specific method:

@Injectable()
export class MyService {
  @OtelMethodCounter()
  doSomething() {}
}
@Controller()
export class AppController {
  @Get()
  @OtelMethodCounter() // It will generate `app_AppController_doSomething_calls_total` counter.
  doSomething() {
    // do your stuff
  }
}

Metric Param Decorator

You have the following decorators:

• @OtelCounter()
• @OtelUpDownCounter()
• @OtelHistogram()
• @OtelGauge()
• @OtelObservableGauge()
• @OtelObservableCounter()
• @OtelObservableUpDownCounter()

Example of usage:

import { OtelCounter } from 'nestjs-otel';
import { Counter } from '@opentelemetry/api';

@Controller()
export class AppController {
  @Get('/home')
  home(
    @OtelCounter('app_counter_1_inc', { description: 'counter 1 description' }) counter1: Counter
  ) {
    counter1.add(1);
  }
}

Prometheus Metrics

When metricExporter is defined in otel SDK with a PrometheusExporterit will start a new process on port 8081 (default port) and metrics will be available at http://localhost:8081/metrics.

Using with a logger

Pino with instrumentation

This approach uses otel instrumentation to automatically inject spanId and traceId.

import { PinoInstrumentation } from '@opentelemetry/instrumentation-pino';

const otelSDK = new NodeSDK({
  instrumentations: [new PinoInstrumentation()],
});

Pino with custom formatter

This approach uses the global trace context for injecting SpanId and traceId as a property of your structured log.

import Pino, { Logger } from 'pino';
import { LoggerOptions } from 'pino';
import { trace, context } from '@opentelemetry/api';

export const loggerOptions: LoggerOptions = {
  formatters: {
    log(object) {
      const span = trace.getSpan(context.active());
      if (!span) return { ...object };
      const { spanId, traceId } = trace.getSpan(context.active())?.spanContext();
      return { ...object, spanId, traceId };
    },
  },
};

export const logger: Logger = Pino(loggerOptions);

Stargazers over time