@ryanzeng/nest-observe 0.1.3 → 0.1.5

package/README.md

@@ -1,4 +1,4 @@
-# @ryanzeng/nest-observe
+![header](https://capsule-render.vercel.app/api?type=waving&color=gradient&height=220&section=header&text=nest-observe&fontSize=48&fontColor=ffffff&animation=fadeIn)
 
 面向 NestJS 的零配置、Vendor Neutral Observability SDK。基于 OpenTelemetry，通过标准 OTLP 同时发送 Traces、Metrics 和 Logs，可连接 OpenObserve、Grafana、Jaeger、Datadog、Elastic 等兼容后端。
 
@@ -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,45 @@ 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`
-- 对象和数组消息会在脱敏后保持结构化 body，由观测后端或查询侧决定如何展开、展示或序列化
+- 遵循 Nest `ConsoleLogger` 的重载解析语义，保留 `error(message, stack?, context?)`、附加消息和结构化参数
+- `Error` 或显式 stack 会映射为 OTLP `exception.type`、`exception.message`、`exception.stacktrace` 属性
+- 尊重 Nest 11+ 的实例级日志级别过滤（`logLevels` / `setLogLevels` / `Logger.overrideLogger`），上传内容与控制台输出一致
+- 对象和数组消息会在脱敏后保持结构化 body；附加的结构化参数会展开为 OTLP attributes，同时保持首个 message 为 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

@@ -1,10 +1,10 @@
 import { LogRecordExporter, LoggerProvider } from '@opentelemetry/sdk-logs';
 import { MetricReader, MeterProvider } from '@opentelemetry/sdk-metrics';
 import { SpanExporter, SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-base';
-import { Attributes, Meter, Tracer, Span, Context } from '@opentelemetry/api';
-import { Logger } from '@opentelemetry/api-logs';
+import { LogAttributes, Logger } from '@opentelemetry/api-logs';
 import { InstrumentationConfig, InstrumentationNodeModuleDefinition } from '@opentelemetry/instrumentation';
 import { NestInstrumentation } from '@opentelemetry/instrumentation-nestjs-core';
+import { Meter, Tracer, Span, Context } from '@opentelemetry/api';
 import { IncomingMessage, ServerResponse } from 'node:http';
 import { NestInterceptor, ExecutionContext, CallHandler, DynamicModule } from '@nestjs/common';
 import { Observable } from 'rxjs';
@@ -109,7 +109,7 @@ declare function Trace(nameOrOptions?: string | TraceOptions): TraceDecorator;
 interface StructuredLogRecord {
     body: unknown;
     severityText: 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'FATAL';
-    attributes: Attributes;
+    attributes: LogAttributes;
     timestamp?: number;
 }
 interface StructuredLogEmitter {

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import { LogRecordExporter, LoggerProvider } from '@opentelemetry/sdk-logs';
 import { MetricReader, MeterProvider } from '@opentelemetry/sdk-metrics';
 import { SpanExporter, SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-base';
-import { Attributes, Meter, Tracer, Span, Context } from '@opentelemetry/api';
-import { Logger } from '@opentelemetry/api-logs';
+import { LogAttributes, Logger } from '@opentelemetry/api-logs';
 import { InstrumentationConfig, InstrumentationNodeModuleDefinition } from '@opentelemetry/instrumentation';
 import { NestInstrumentation } from '@opentelemetry/instrumentation-nestjs-core';
+import { Meter, Tracer, Span, Context } from '@opentelemetry/api';
 import { IncomingMessage, ServerResponse } from 'node:http';
 import { NestInterceptor, ExecutionContext, CallHandler, DynamicModule } from '@nestjs/common';
 import { Observable } from 'rxjs';
@@ -109,7 +109,7 @@ declare function Trace(nameOrOptions?: string | TraceOptions): TraceDecorator;
 interface StructuredLogRecord {
     body: unknown;
     severityText: 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'FATAL';
-    attributes: Attributes;
+    attributes: LogAttributes;
     timestamp?: number;
 }
 interface StructuredLogEmitter {

package/dist/index.js

@@ -347,6 +347,71 @@ function bodyValue(message) {
     return redactText(message.stack ?? `${message.name}: ${message.message}`);
   return redact(message);
 }
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype === null) return true;
+  const constructor = Object.prototype.hasOwnProperty.call(prototype, "constructor") ? prototype.constructor : void 0;
+  return typeof constructor === "function" && constructor instanceof constructor && Function.prototype.toString.call(constructor) === Function.prototype.toString.call(Object);
+}
+function isStackFormat(value) {
+  return typeof value === "string" && /^(.)+\n\s+at .+:\d+:\d+/.test(value);
+}
+function fallbackMessages(logger, values) {
+  if (values.length <= 1) return { messages: values, context: logger.context };
+  const lastValue = values.at(-1);
+  const contextName = typeof lastValue === "string" ? lastValue : logger.context;
+  const remaining = typeof lastValue === "string" ? values.slice(0, -1) : values;
+  if (logger.options?.structuredParams === false) {
+    return { messages: remaining, context: contextName };
+  }
+  const messages = [remaining[0]];
+  const structuredParams = [];
+  for (const value of remaining.slice(1)) {
+    if (isPlainObject(value)) structuredParams.push(value);
+    else messages.push(value);
+  }
+  const params = structuredParams.length > 0 ? Object.assign({}, ...structuredParams) : void 0;
+  return { messages, context: contextName, ...params ? { params } : {} };
+}
+function fallbackError(logger, values) {
+  if (values.length === 2) {
+    if (isStackFormat(values[1])) {
+      return { messages: [values[0]], stack: values[1], context: logger.context };
+    }
+    return fallbackMessages(logger, values);
+  }
+  const trailingValue = values.at(-1);
+  if (isStackFormat(trailingValue)) {
+    return { ...fallbackMessages(logger, values.slice(0, -1)), stack: trailingValue };
+  }
+  const parsed = fallbackMessages(logger, values);
+  if (parsed.messages.length <= 1) return parsed;
+  const possibleStack = parsed.messages.at(-1);
+  if (typeof possibleStack !== "string" && possibleStack !== void 0) return parsed;
+  return {
+    ...parsed,
+    messages: parsed.messages.slice(0, -1),
+    ...possibleStack === void 0 ? {} : { stack: possibleStack }
+  };
+}
+function parseLogCall(logger, method, message, args) {
+  const values = [message, ...args];
+  const nestParser = method === "error" ? logger.getContextAndStackAndMessagesToPrint : logger.getContextAndMessagesToPrint;
+  if (typeof nestParser === "function") return nestParser.call(logger, values);
+  return method === "error" ? fallbackError(logger, values) : fallbackMessages(logger, values);
+}
+function exceptionAttributes(message, stack) {
+  const error = message instanceof Error ? message : void 0;
+  const stacktrace = stack ?? error?.stack;
+  return {
+    ...error ? {
+      "exception.type": error.name,
+      "exception.message": redactText(error.message)
+    } : {},
+    ...stacktrace ? { "exception.stacktrace": redactText(stacktrace) } : {}
+  };
+}
 var NestLoggerInstrumentation = class {
   constructor(emitter, resourceAttributes = {}) {
     this.emitter = emitter;
@@ -368,18 +433,30 @@ 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 };
-          if (contextName) attributes["nestjs.context"] = contextName;
-          if (spanContext?.traceId) attributes.trace_id = spanContext.traceId;
-          if (spanContext?.spanId) attributes.span_id = spanContext.spanId;
-          emitter.emit({
-            body: bodyValue(message),
-            severityText: SEVERITY[method],
-            attributes,
-            timestamp: Date.now()
-          });
+          const parsed = parseLogCall(this, method, message, args);
+          const timestamp = Date.now();
+          for (const parsedMessage of parsed.messages) {
+            const params = parsed.params ? redact(parsed.params) : {};
+            const attributes = {
+              ...params,
+              ...resourceAttributes,
+              ...exceptionAttributes(parsedMessage, parsed.stack)
+            };
+            if (parsed.context) attributes["nestjs.context"] = parsed.context;
+            if (spanContext?.traceId) attributes.trace_id = spanContext.traceId;
+            if (spanContext?.spanId) attributes.span_id = spanContext.spanId;
+            emitter.emit({
+              body: bodyValue(parsedMessage),
+              severityText: SEVERITY[method],
+              attributes,
+              timestamp
+            });
+          }
         } catch {
         }
         return original.call(this, message, ...args);
@@ -697,7 +774,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");
@@ -863,7 +939,7 @@ var import_node_os2 = require("os");
 // package.json
 var package_default = {
   name: "@ryanzeng/nest-observe",
-  version: "0.1.3",
+  version: "0.1.4",
   description: "Zero-config, vendor-neutral OpenTelemetry observability for NestJS",
   keywords: [
     "nestjs",
@@ -948,8 +1024,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",
@@ -1264,7 +1339,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 } : {},