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

NestJS OpenTelemetry (OTEL) 完全指南从入门到精通的一站式教程【免费下载链接】nestjs-otelOpenTelemetry (Tracing Metrics) module for Nest framework (node.js) 项目地址: https://gitcode.com/gh_mirrors/ne/nestjs-otelNestJS OpenTelemetryOTEL模块是专为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 --save2. 安装可选依赖根据需要的导出器类型安装额外依赖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 SDKimport 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装饰器在控制器中获取当前spanimport { 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 EventsWide Events宽事件模式在单个请求生命周期中累积属性最终生成一个上下文丰富的事件。注册WideEventInterceptorimport { 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考