NestJS OpenTelemetry 自动注入模块

这是一个用于 NestJS 框架的 OpenTelemetry 自动注入模块，它可以自动为你的应用添加分布式追踪能力，无需手动修改大量代码。

English Documentation

特性

• 🚀 自动注入追踪功能到 NestJS 应用的各个层面
• 🎯 支持多种注入器，覆盖常见场景：
  • Controller 注入器
  • Provider 注入器
  • Middleware 注入器
  • Guard 注入器
  • Interceptor 注入器
  • Pipe 注入器
  • Schedule 注入器
  • TypeORM 注入器
  • Logger 注入器
• 📊 自动收集关键性能指标
• 🔍 详细的追踪信息，包括：
  • 模块名称
  • 控制器名称
  • 方法名称
  • 数据库操作
  • 中间件执行
  • 守卫验证
  • 拦截器处理
  • 管道转换
  • 定时任务执行

安装

npm install @nest-otel/k8s
# 或
pnpm add @nest-otel/k8s
# 或
yarn add @nest-otel/k8s

快速开始

1. 在你的 NestJS 应用的 app.module.ts 中导入 OpenTelemetryModule：

import { OpenTelemetryModule } from '@nest-otel/k8s';

@Module({
  imports: [
    OpenTelemetryModule.forRoot({
      // 可选配置
    }),
  ],
})
export class AppModule {}

2. 使用异步配置（可选）：

import { OpenTelemetryModule } from '@nest-otel/k8s';

@Module({
  imports: [
    OpenTelemetryModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: async (configService: ConfigService) => ({
        // 异步配置选项
      }),
    }),
  ],
})
export class AppModule {}

装饰器使用

@Trace 装饰器

你可以使用 @Trace 装饰器来手动标记需要追踪的方法：

import { Trace } from '@nest-otel/k8s';

@Injectable()
export class UserService {
  @Trace('get-user-by-id')
  async getUserById(id: string) {
    // 方法实现
  }
}

TracePlain 装饰器

用于普通类方法的追踪：

import { TracePlain } from '@nest-otel/k8s';

@TracePlain()
class MyClass {
  myMethod() {
    // 方法实现
  }
}

配置选项

interface OpenTelemetryModuleOptions {
  autoInjectors?: Type<any>[]; // 自定义注入器
  injectorsConfig?: Record<string, any>; // 注入器配置
}

TypeORM 配置示例

OpenTelemetryModule.forRoot({
  injectorsConfig: {
    TypeormInjector: {
      collectParameters: true, // 收集SQL参数
    },
  },
});

自定义注入器

你可以创建自己的注入器来扩展功能：

@Injectable()
export class CustomInjector extends BaseInjector {
  inject(): void {
    // 实现注入逻辑
  }
}

// 在模块配置中使用
OpenTelemetryModule.forRoot({
  autoInjectors: [CustomInjector],
});

注意事项

• 确保在应用启动前配置 OpenTelemetry
• TypeORM 注入器需要 TypeORM 包的支持
• 建议在生产环境中谨慎使用参数收集功能，可能会影响性能

许可证

MIT

贡献指南

欢迎提交 Issue 和 Pull Request！