@ryanzeng/nest-observe 0.1.2 → 0.1.4

package/README.md

@@ -44,7 +44,7 @@ OBSERVE_ENVIRONMENT=production
 
 ## Nest Module
 
-`register` 已能在加载阶段自动挂载 HTTP、Nest Controller、Provider、Prisma 和 Logger instrumentation。也可以导入全局 Module；它为较晚初始化或测试场景提供 Discovery fallback，并在 Nest 关闭时 flush/shutdown：
+`register` 已能在加载阶段自动挂载 HTTP、Nest Controller、Provider 和 Logger instrumentation。也可以导入全局 Module；它为较晚初始化或测试场景提供 Discovery fallback，并在 Nest 关闭时 flush/shutdown：
 
 ```ts
 import { Module } from '@nestjs/common';
@@ -58,6 +58,75 @@ export class AppModule {}
 
 Module-only 模式还会注册一个全局 Nest interceptor，补采因 HTTP 模块已经加载而无法挂载底层 hook 的已匹配 Controller 请求指标。它与早期 HTTP instrumentation 共享请求状态，不会重复计数。
 
+## 可选 Instrumentation
+
+核心包不内置 Prisma、Redis 或其他数据库客户端 instrumentation。应用只安装自己实际使用的适配包，并在目标客户端被加载之前注册：
+
+```bash
+# Prisma
+pnpm add @prisma/instrumentation
+
+# node-redis
+pnpm add @opentelemetry/instrumentation-redis
+
+# ioredis
+pnpm add @opentelemetry/instrumentation-ioredis
+
+# Pino / Winston（日志类，见"自动采集内容 → Logs"）
+pnpm add @opentelemetry/instrumentation-pino
+pnpm add @opentelemetry/instrumentation-winston
+```
+
+创建一个只负责注册应用级 instrumentation 的文件，例如 `src/observability.instrumentation.ts`：
+
+```ts
+import { registerInstrumentations } from '@opentelemetry/instrumentation';
+import { PrismaInstrumentation } from '@prisma/instrumentation';
+import { IORedisInstrumentation } from '@opentelemetry/instrumentation-ioredis';
+
+export const unregisterApplicationInstrumentations = registerInstrumentations({
+  instrumentations: [
+    new PrismaInstrumentation(),
+    new IORedisInstrumentation(),
+  ],
+});
+```
+
+如果应用使用的是 `redis` 包而不是 `ioredis`，替换为：
+
+```ts
+import { RedisInstrumentation } from '@opentelemetry/instrumentation-redis';
+
+new RedisInstrumentation();
+```
+
+然后将注册文件放在应用入口的最前面。使用早期 `register` 初始化时：
+
+```ts
+import './observability.instrumentation';
+import '@ryanzeng/nest-observe/register';
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+```
+
+仅使用 `ObserveModule.forRoot()` 时同样先加载应用级 instrumentation：
+
+```ts
+import './observability.instrumentation';
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+```
+
+应用级 instrumentation 会使用 `nest-observe` 注册的全局 tracer provider，因此不应再创建第二个 `NodeTracerProvider` 或第二套 OTLP exporter。对于会重排 import 的 bundler，生产环境应使用 Node 的 `--require`（CommonJS）或 `--import`（ESM）预加载编译后的 instrumentation 文件，确保它早于 Prisma/Redis 客户端执行。
+
+### 为什么必须放在入口第一条 import
+
+OTel instrumentation 通过 hook Node 的模块加载器工作：当目标模块（如 `@prisma/client`）第一次被 require/import 时，hook 替换它的导出（`PrismaClient` 类等）；模块一旦进入 `require.cache`，加载流程不会再走一遍，hook 永远不会再触发。事后补救也不可行——ESM 命名空间只读，CJS 下应用已持有的类引用也不受缓存修改影响。
+
+而 import 的求值顺序是"先 imports、后模块体"：`import { AppModule }` 会把整个依赖图（包括 `PrismaService` → `@prisma/client`）加载完，之后才执行 main.ts 的函数体。因此任何运行在 Nest DI 生命周期里的注册（包括 `ObserveModule.forRoot()`）都晚于客户端加载——这正是 `forRoot()` 不提供第三方客户端 instrumentation 参数的原因，只有 import 声明顺序的第一位早于它。Nest 语义层采集（Controller/Provider 方法）不受此限制：那些对象由 DI 在运行时逐个创建，天然晚于 instrumentation 就位。
+
+OTel 官方对"注册过晚"的处理同样只是警告、无法补救（`_warnOnPreloadedModules`），所以放错位置的注册不会报错，只会静默失效——排查"span 没有出现"问题时，请先检查注册文件是否在入口第一条 import。
+
 ## 装饰器
 
 ```ts
@@ -90,17 +159,43 @@ export class OrderService {
 Traces：
 
 - Node HTTP client/server、Nest Controller/handler、Provider method
-- Prisma instrumentation
+- 应用可按需组合 Prisma、Redis、ioredis 等标准 OpenTelemetry instrumentation
 - `@Trace()` 自定义 span 和自然 parent/child context
 - Controller/Provider 异常事件、错误状态及 stack trace
 
 Logs：
 
 - 默认 Nest `Logger` 的 `verbose/debug/log/warn/error/fatal`
-- 对象和数组消息会在脱敏后序列化成 JSON 字符串，保证 OpenObserve 的标准 `body` 字段始终可见
+- 尊重 Nest 11+ 的实例级日志级别过滤（`logLevels` / `setLogLevels` / `Logger.overrideLogger`），上传内容与控制台输出一致
+- 对象和数组消息会在脱敏后保持结构化 body，由观测后端或查询侧决定如何展开、展示或序列化
 - OTLP severity、`nestjs.context`、`trace_id`、`span_id`
 - `service.name`、`service.version`、`deployment.environment.name`
-- `StructuredLogEmitter` 抽象可用于后续 Pino/Winston adapter
+
+**采集边界**：自动桥接覆盖所有经过 `ConsoleLogger` 的日志（包括默认 `Logger`）。自定义 `LoggerService` 若完全不经过 `ConsoleLogger`（例如直接封装 Pino/Winston），不会被自动采集。两种接入方式：
+
+一是用 `StructuredLogEmitter` 桥接，在自定义 Logger 里显式 emit：
+
+```ts
+import { Injectable, LoggerService } from '@nestjs/common';
+import { OpenTelemetryLogEmitter, redact } from '@ryanzeng/nest-observe';
+
+@Injectable()
+export class CustomLogger implements LoggerService {
+  private readonly emitter = new OpenTelemetryLogEmitter();
+
+  error(message: unknown, context?: string): void {
+    // 继续执行你的 Pino/Winston 输出……
+    this.emitter.emit({
+      body: redact(message),
+      severityText: 'ERROR',
+      attributes: context ? { 'nestjs.context': context } : {},
+      timestamp: Date.now(),
+    });
+  }
+}
+```
+
+二是注册 OTel 官方的 `@opentelemetry/instrumentation-pino` 或 `@opentelemetry/instrumentation-winston`（方式同上方"可选 Instrumentation"），日志会使用 SDK 注册的全局 Logger Provider，进入同一条 OTLP 管道。
 
 Metrics：
 

package/dist/index.d.mts

@@ -177,8 +177,8 @@ declare class NestMethodInstrumenter {
     private readonly errors;
     private readonly instrumented;
     constructor(tracer: Tracer, meter: Meter);
-    instrumentInstance(instance: object, kind: NestComponentKind, componentName?: string): void;
-    instrumentPrototype(type: Function, kind: NestComponentKind, componentName?: string): void;
+    instrumentInstance(instance: object, kind: NestComponentKind, componentName?: unknown): void;
+    instrumentPrototype(type: Function, kind: NestComponentKind, componentName?: unknown): void;
     private instrumentTarget;
 }
 

package/dist/index.d.ts

@@ -177,8 +177,8 @@ declare class NestMethodInstrumenter {
     private readonly errors;
     private readonly instrumented;
     constructor(tracer: Tracer, meter: Meter);
-    instrumentInstance(instance: object, kind: NestComponentKind, componentName?: string): void;
-    instrumentPrototype(type: Function, kind: NestComponentKind, componentName?: string): void;
+    instrumentInstance(instance: object, kind: NestComponentKind, componentName?: unknown): void;
+    instrumentPrototype(type: Function, kind: NestComponentKind, componentName?: unknown): void;
     private instrumentTarget;
 }
 

package/dist/index.js

@@ -233,6 +233,11 @@ function invokeWithSpan(tracer, spanName, attributes, invoke, onFinish) {
 }
 
 // src/decorators/trace.decorator.ts
+function copyOwnMetadata(source, target) {
+  for (const metadataKey of Reflect.getOwnMetadataKeys(source)) {
+    Reflect.defineMetadata(metadataKey, Reflect.getOwnMetadata(metadataKey, source), target);
+  }
+}
 function decorateMethod(target, propertyKey, descriptor, options) {
   const original = descriptor.value;
   if (typeof original !== "function" || isTraceIgnored(original, target.constructor))
@@ -257,6 +262,7 @@ function decorateMethod(target, propertyKey, descriptor, options) {
     value: original.name,
     configurable: true
   });
+  copyOwnMetadata(original, wrapped);
   markTraceDecorated(wrapped);
   descriptor.value = wrapped;
 }
@@ -337,14 +343,9 @@ var SEVERITY = {
   fatal: "FATAL"
 };
 function bodyValue(message) {
-  if (message instanceof Error) return redactText(message.stack ?? `${message.name}: ${message.message}`);
-  const sanitized = redact(message);
-  if (sanitized === null || typeof sanitized !== "object") return sanitized;
-  try {
-    return JSON.stringify(sanitized, (_key, value) => typeof value === "bigint" ? value.toString() : value);
-  } catch {
-    return redactText(String(sanitized));
-  }
+  if (message instanceof Error)
+    return redactText(message.stack ?? `${message.name}: ${message.message}`);
+  return redact(message);
 }
 var NestLoggerInstrumentation = class {
   constructor(emitter, resourceAttributes = {}) {
@@ -367,6 +368,10 @@ var NestLoggerInstrumentation = class {
       const resourceAttributes = this.resourceAttributes;
       prototype[method] = function(message, ...args) {
         try {
+          const gated = this;
+          if (typeof gated.isLevelEnabled === "function" && !gated.isLevelEnabled(method)) {
+            return original.call(this, message, ...args);
+          }
           const spanContext = import_api3.trace.getActiveSpan()?.spanContext();
           const contextName = this.context ?? (typeof args.at(-1) === "string" ? String(args.at(-1)) : void 0);
           const attributes = { ...resourceAttributes };
@@ -388,7 +393,8 @@ var NestLoggerInstrumentation = class {
   disable() {
     if (!this.enabled) return;
     const prototype = import_common.ConsoleLogger.prototype;
-    for (const [method, original] of this.originals) prototype[method] = original;
+    for (const [method, original] of this.originals)
+      prototype[method] = original;
     this.originals.clear();
     this.enabled = false;
   }
@@ -464,7 +470,7 @@ var NestMethodInstrumenter = class {
       if (!descriptor || typeof original !== "function" || isTraceIgnored(original, type) || isTraceDecorated(original)) continue;
       const existing = Reflect.get(target, methodName);
       if (typeof existing === "function" && existing !== original && isTraceDecorated(existing)) continue;
-      const name = componentName || type.name || "Anonymous";
+      const name = typeof componentName === "symbol" ? String(componentName) : typeof componentName === "string" && componentName ? componentName : type.name || "Anonymous";
       const attributes = {
         [`nestjs.${kind}`]: name,
         "nestjs.method": methodName
@@ -517,7 +523,7 @@ var CompatibleNestInstrumentation = class extends import_instrumentation_nestjs_
               const instance = await original.apply(this, args);
               try {
                 const wrapper = args[1];
-                if (!instance || typeof instance !== "object" || !wrapper?.metatype) return instance;
+                if (!instance || typeof instance !== "object" || !wrapper?.metatype || wrapper.inject !== void 0) return instance;
                 if (["InternalCoreModule", "ObserveModule", "DiscoveryModule"].includes(wrapper.host?.name ?? "")) {
                   return instance;
                 }
@@ -695,7 +701,6 @@ var import_exporter_metrics_otlp_proto = require("@opentelemetry/exporter-metric
 var import_exporter_trace_otlp_proto = require("@opentelemetry/exporter-trace-otlp-proto");
 var import_instrumentation2 = require("@opentelemetry/instrumentation");
 var import_instrumentation_http = require("@opentelemetry/instrumentation-http");
-var import_instrumentation3 = require("@prisma/instrumentation");
 var import_sdk_logs = require("@opentelemetry/sdk-logs");
 var import_sdk_metrics = require("@opentelemetry/sdk-metrics");
 var import_sdk_trace_base = require("@opentelemetry/sdk-trace-base");
@@ -861,7 +866,7 @@ var import_node_os2 = require("os");
 // package.json
 var package_default = {
   name: "@ryanzeng/nest-observe",
-  version: "0.1.2",
+  version: "0.1.4",
   description: "Zero-config, vendor-neutral OpenTelemetry observability for NestJS",
   keywords: [
     "nestjs",
@@ -946,8 +951,7 @@ var package_default = {
     "@opentelemetry/sdk-logs": "^0.221.0",
     "@opentelemetry/sdk-metrics": "^2.10.0",
     "@opentelemetry/sdk-trace-base": "^2.10.0",
-    "@opentelemetry/sdk-trace-node": "^2.10.0",
-    "@prisma/instrumentation": "^7.10.0"
+    "@opentelemetry/sdk-trace-node": "^2.10.0"
   },
   devDependencies: {
     "@nestjs/common": "^12.0.1",
@@ -1262,7 +1266,6 @@ function observe(options = {}) {
         providerTracing: config.providerTracing,
         controllerTracing: config.controllerTracing
       }));
-      if (config.traces) instrumentations.push(new import_instrumentation3.PrismaInstrumentation());
       (0, import_instrumentation2.registerInstrumentations)({
         instrumentations,
         ...tracerProvider ? { tracerProvider } : {},
@@ -1367,7 +1370,7 @@ var NestObserveExplorer = class {
   }
   instrument(wrappers, instrumenter, kind) {
     for (const wrapper of wrappers) {
-      if (!wrapper.metatype) continue;
+      if (!wrapper.metatype || wrapper.inject !== void 0) continue;
       if (["ObserveModule", "DiscoveryModule", "InternalCoreModule"].includes(wrapper.host?.name ?? "")) continue;
       if (wrapper.metatype === NestObserveExplorer) continue;
       if (wrapper.instance) {