NestJS OpenTelemetry (OTEL) 完全指南：从入门到精通的一站式教程

NestJS OpenTelemetry (OTEL) 完全指南：从入门到精通的一站式教程

【免费下载链接】nestjs-otelOpenTelemetry (Tracing + Metrics) module for Nest framework (node.js) 🔭项目地址: https://gitcode.com/gh_mirrors/ne/nestjs-otel

NestJS OpenTelemetry（OTEL）模块是专为Nest框架设计的可观测性解决方案，它整合了OpenTelemetry的追踪（Tracing）和指标（Metrics）功能，帮助开发者轻松构建可观测的Node.js应用。本教程将带你从基础安装到高级功能应用，掌握NestJS应用的可观测性实践。

为什么选择NestJS OpenTelemetry？

在现代微服务架构中，可观测性至关重要。OpenTelemetry提供了统一的标准，支持多种数据导出和指标类型（如Prometheus指标）。nestjs-otel模块简化了OpenTelemetry在NestJS应用中的集成，让开发者无需深入了解底层细节即可实现分布式追踪和性能监控。

核心概念：可观测性三支柱

可观测性建立在三个核心信号之上：

• 追踪（Tracing）：记录请求在系统中的传播路径，帮助定位性能瓶颈
• 指标（Metrics）：量化系统行为，如请求量、错误率、响应时间
• 日志（Logs）：记录系统事件，提供调试上下文

图：NestJS OpenTelemetry可观测性三支柱示意图

快速安装步骤

1. 安装核心依赖

npm i nestjs-otel @opentelemetry/sdk-node --save

2. 安装可选依赖

根据需要的导出器类型安装额外依赖：

npm i @opentelemetry/exporter-prometheus --save

基础配置指南

创建Tracing配置文件

在项目根目录创建tracing.ts文件：

import { NodeSDK } from '@opentelemetry/sdk-node'; import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'; import { PrometheusExporter } from '@opentelemetry/exporter-prometheus'; import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base'; import { JaegerExporter } from '@opentelemetry/exporter-jaeger'; import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks'; const otelSDK = new NodeSDK({ metricReader: new PrometheusExporter({ port: 8081 }), spanProcessor: new BatchSpanProcessor(new JaegerExporter()), contextManager: new AsyncLocalStorageContextManager(), instrumentations: [getNodeAutoInstrumentations()], }); export default otelSDK;

集成到NestJS应用

在应用入口文件（通常是main.ts）中启动OTEL SDK：

import otelSDK from './tracing'; import { NestFactory } from '@nestjs/core'; import { AppModule } from './app.module'; async function bootstrap() { // 在创建Nest应用前启动OTEL SDK await otelSDK.start(); const app = await NestFactory.create(AppModule); await app.listen(3000); } bootstrap();

注册OpenTelemetry模块

在AppModule中配置OpenTelemetry模块：

import { OpenTelemetryModule } from 'nestjs-otel'; @Module({ imports: [ OpenTelemetryModule.forRoot({ metrics: { hostMetrics: true } // 启用主机指标收集 }) ] }) export class AppModule {}

追踪功能详解

使用@Span装饰器创建自定义追踪

@Span装饰器可用于标记需要追踪的方法，支持自定义名称和属性：

import { Span } from 'nestjs-otel'; export class BooksService { // 自定义span名称 @Span('getBooks') async getBooks() { return ['Harry Potter', 'The Hobbit']; } // 动态设置span属性 @Span((id) => ({ attributes: { bookId: id } })) async getBook(id: number) { return { id, title: 'NestJS in Action' }; } }

使用@Traceable装饰器追踪类所有方法

对类使用@Traceable装饰器可自动追踪所有方法：

import { Traceable } from 'nestjs-otel'; @Injectable() @Traceable() export class UsersService { findAll() { return []; } findOne(id: string) { return {}; } }

访问当前Span

使用@CurrentSpan装饰器在控制器中获取当前span：

import { Controller, Get } from '@nestjs/common'; import { CurrentSpan } from 'nestjs-otel'; import { Span } from '@opentelemetry/api'; @Controller('cats') export class CatsController { @Get() findAll(@CurrentSpan() span: Span) { span?.setAttribute('custom.attribute', 'value'); return 'This action returns all cats'; } }

指标监控实战

使用MetricService创建指标

通过MetricService可以创建和管理各种类型的指标：

import { MetricService } from 'nestjs-otel'; import { Counter } from '@opentelemetry/api'; @Injectable() export class BookService { private bookCounter: Counter; constructor(private metricService: MetricService) { this.bookCounter = this.metricService.getCounter('book_requests_total', { description: 'Total number of book requests' }); } async getBooks() { this.bookCounter.add(1); return ['Book 1', 'Book 2']; } }

方法级指标装饰器

使用@OtelMethodCounter装饰器自动统计方法调用次数：

@Controller() export class AppController { @Get() @OtelMethodCounter() // 自动生成 app_AppController_doSomething_calls_total 指标 doSomething() { // 业务逻辑 } }

Prometheus指标导出

配置Prometheus导出器后，指标将在http://localhost:8081/metrics端点可用，可直接被Prometheus抓取。

高级功能：Wide Events

Wide Events（宽事件）模式在单个请求生命周期中累积属性，最终生成一个上下文丰富的事件。

注册WideEventInterceptor

import { APP_INTERCEPTOR } from '@nestjs/core'; import { WideEventInterceptor } from 'nestjs-otel'; @Module({ providers: [ { provide: APP_INTERCEPTOR, useClass: WideEventInterceptor } ] }) export class AppModule {}

使用WideEventService丰富事件

import { WideEventService } from 'nestjs-otel'; @Injectable() export class CheckoutService { constructor(private wideEvent: WideEventService) {} async checkout(cart: Cart) { this.wideEvent.setMany({ 'user.id': cart.userId, 'cart.items': cart.items.length, 'cart.total': cart.total }); const timer = this.wideEvent.startTimer('payment.duration_ms'); await this.processPayment(cart); timer(); // 停止计时并记录 } }

与日志集成

Pino日志集成

通过OpenTelemetry instrumentation自动将traceId和spanId注入日志：

import { PinoInstrumentation } from '@opentelemetry/instrumentation-pino'; const otelSDK = new NodeSDK({ instrumentations: [new PinoInstrumentation()] });

完整示例项目

查看完整的示例项目，包含NestJS应用与Prometheus、Grafana、Loki和Tempo的集成：

• nestjs-otel-prom-grafana-tempo

总结

NestJS OpenTelemetry模块为Nest应用提供了强大的可观测性能力，通过简单的配置和装饰器即可实现分布式追踪和指标监控。无论是小型项目还是大型微服务架构，nestjs-otel都能帮助你构建更可靠、更易于维护的应用系统。

开始使用NestJS OpenTelemetry，提升你的应用可观测性，快速定位问题，优化性能！

【免费下载链接】nestjs-otelOpenTelemetry (Tracing + Metrics) module for Nest framework (node.js) 🔭项目地址: https://gitcode.com/gh_mirrors/ne/nestjs-otel