@ryanzeng/nest-observe 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Zeng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+# @ryanzeng/nest-observe
+
+面向 NestJS 的零配置、Vendor Neutral Observability SDK。基于 OpenTelemetry，通过标准 OTLP 同时发送 Traces、Metrics 和 Logs，可连接 OpenObserve、Grafana、Jaeger、Datadog、Elastic 等兼容后端。
+
+## 快速开始
+
+```bash
+pnpm add @ryanzeng/nest-observe
+```
+
+把注册入口放在应用入口的第一条 import（必须早于 `@nestjs/core` 和业务模块）：
+
+```ts
+import '@ryanzeng/nest-observe/register';
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+}
+
+void bootstrap();
+```
+
+设置标准 OpenTelemetry 环境变量：
+
+```env
+OTEL_SERVICE_NAME=mall-app
+OTEL_SERVICE_VERSION=1.0.0
+OTEL_EXPORTER_OTLP_ENDPOINT=https://observe.example.com
+OTEL_EXPORTER_OTLP_HEADERS=Authorization=Basic%20xxx
+OTEL_RESOURCE_ATTRIBUTES=git.commit.sha=abc123
+OBSERVE_ENVIRONMENT=production
+```
+
+通用 endpoint 会自动派生 `/v1/traces`、`/v1/metrics` 和 `/v1/logs`。也可使用标准的 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`、`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`、`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` 分别覆盖。
+
+初始化或 exporter 配置失败时，SDK 会降级为 no-op，不会阻止业务应用启动。
+
+## Nest Module
+
+`register` 已能在加载阶段自动挂载 HTTP、Nest Controller、Provider、Prisma 和 Logger instrumentation。也可以导入全局 Module；它为较晚初始化或测试场景提供 Discovery fallback，并在 Nest 关闭时 flush/shutdown：
+
+```ts
+import { Module } from '@nestjs/common';
+import { ObserveModule } from '@ryanzeng/nest-observe';
+
+@Module({
+  imports: [ObserveModule.forRoot()],
+})
+export class AppModule {}
+```
+
+## 装饰器
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { IgnoreTrace, Trace } from '@ryanzeng/nest-observe';
+
+@Injectable()
+export class OrderService {
+  @Trace('order.create')
+  async createOrder() {
+    return this.reserveInventory();
+  }
+
+  @Trace()
+  private async reserveInventory() {
+    // 自动成为 order.create 的 child span
+  }
+
+  @IgnoreTrace()
+  healthCheck() {
+    return 'ok';
+  }
+}
+```
+
+`@Trace()` 支持同步函数、Promise 和 RxJS Observable，自动记录耗时、异常、ERROR status，并继承当前 context。`@Trace()` 也可应用在 class 上。
+
+## 自动采集内容
+
+Traces：
+
+- Node HTTP client/server、Nest Controller/handler、Provider method
+- Prisma instrumentation
+- `@Trace()` 自定义 span 和自然 parent/child context
+- Controller/Provider 异常事件、错误状态及 stack trace
+
+Logs：
+
+- 默认 Nest `Logger` 的 `verbose/debug/log/warn/error/fatal`
+- OTLP severity、`nestjs.context`、`trace_id`、`span_id`
+- `service.name`、`service.version`、`deployment.environment.name`
+- `StructuredLogEmitter` 抽象可用于后续 Pino/Winston adapter
+
+Metrics：
+
+- `system.cpu.utilization`、`process.cpu.time`
+- `process.memory.rss`、`nodejs.memory.heap.used`、`nodejs.memory.heap.total`
+- `nodejs.eventloop.delay`、`nodejs.eventloop.utilization`
+- `nodejs.gc.duration`、`process.uptime`
+- `http.server.request.count`、`http.server.request.duration`、`http.server.error.count`
+- `nestjs.method.calls`、`nestjs.method.duration`、`nestjs.method.errors`
+
+HTTP 与 Nest method 指标只使用 route template、method、status、controller/provider/method 等有限维度，避免把 URL id 或请求数据变成高基数标签。
+
+## 程序化配置
+
+```ts
+import { observe } from '@ryanzeng/nest-observe';
+
+const telemetry = observe({
+  serviceName: 'mall-app',
+  serviceVersion: '1.0.0',
+  environment: 'production',
+  traces: true,
+  logs: true,
+  metrics: true,
+  providerTracing: true,
+  controllerTracing: true,
+  sampling: 0.1,
+  allowedHeaders: ['x-correlation-id'],
+});
+
+await telemetry.forceFlush();
+await telemetry.shutdown();
+```
+
+环境变量方式仍是推荐方式。有合理默认值的配置无需填写。
+
+### Sampling
+
+支持显式 `sampling`（0–1）以及标准环境变量：
+
+```env
+OTEL_TRACES_SAMPLER=parentbased_traceidratio
+OTEL_TRACES_SAMPLER_ARG=0.1
+```
+
+也支持 `always_on`、`always_off`、`parentbased_always_on` 和 `parentbased_always_off`。HTTP/runtime/method metrics 不依赖 trace sampling。
+
+## 安全与隐私
+
+- 不采集 request body、完整 Redis value 或数据库参数。
+- HTTP header 只按白名单采集；默认仅包含 `accept`、`content-type`、`user-agent`、`x-request-id`、`traceparent`。
+- `Authorization`、Cookie、password、secret、token、API key 和手机号字段始终脱敏，即使误加入 header allowlist。
+- 常见签名、token、password 等 URL query 参数由 HTTP instrumentation 脱敏。
+- Batch processor 异步发送，带有有限队列、batch size、export timeout 和 metric cardinality limit。
+
+## 资源属性
+
+三类信号统一带有：
+
+```text
+service.name
+service.version
+deployment.environment.name
+service.instance.id
+telemetry.sdk.name
+telemetry.sdk.version
+host.name
+```
+
+`OTEL_RESOURCE_ATTRIBUTES` 可补充 `git.commit.sha`、`container.id` 等自定义资源信息。
+
+## 开发
+
+项目使用 TDD。完整检查：
+
+```bash
+pnpm install
+pnpm check
+```
+
+最低运行环境为 Node.js 20，支持 NestJS 10、11 和 12。

package/dist/index.d.mts

@@ -0,0 +1,197 @@
+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 { InstrumentationConfig, InstrumentationNodeModuleDefinition } from '@opentelemetry/instrumentation';
+import { NestInstrumentation } from '@opentelemetry/instrumentation-nestjs-core';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { DynamicModule } from '@nestjs/common';
+import { Resource } from '@opentelemetry/resources';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+
+interface ObserveExporters {
+    /** Primarily useful for custom backends and tests. OTLP is used by default. */
+    span?: SpanExporter;
+    log?: LogRecordExporter;
+    metricReader?: MetricReader;
+}
+interface ObserveOptions {
+    enabled?: boolean;
+    serviceName?: string;
+    serviceVersion?: string;
+    environment?: string;
+    instanceId?: string;
+    endpoint?: string;
+    headers?: Record<string, string>;
+    traces?: boolean;
+    logs?: boolean;
+    metrics?: boolean;
+    providerTracing?: boolean;
+    controllerTracing?: boolean;
+    sampling?: number;
+    allowedHeaders?: string[];
+    exportTimeoutMillis?: number;
+    metricExportIntervalMillis?: number;
+    resourceAttributes?: Record<string, string | number | boolean>;
+    exporters?: ObserveExporters;
+}
+interface ResolvedObserveConfig {
+    enabled: boolean;
+    serviceName: string;
+    serviceVersion: string;
+    environment: string;
+    instanceId: string;
+    endpoints: {
+        traces: string | undefined;
+        metrics: string | undefined;
+        logs: string | undefined;
+    };
+    headers: Record<string, string>;
+    traces: boolean;
+    logs: boolean;
+    metrics: boolean;
+    providerTracing: boolean;
+    controllerTracing: boolean;
+    sampling: number;
+    allowedHeaders: string[];
+    exportTimeoutMillis: number;
+    metricExportIntervalMillis: number;
+    resourceAttributes: Record<string, string | number | boolean>;
+    exporters?: ObserveExporters;
+}
+interface ObserveHandle {
+    readonly started: boolean;
+    readonly config: Readonly<ResolvedObserveConfig>;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+type Environment = Record<string, string | undefined>;
+declare function parseKeyValueList(value?: string): Record<string, string>;
+declare function resolveObserveConfig(options?: ObserveOptions, env?: Environment): ResolvedObserveConfig;
+
+type IgnoreDecorator = MethodDecorator & ClassDecorator;
+declare function IgnoreTrace(): IgnoreDecorator;
+
+declare function markTraceIgnored(target: object): void;
+declare function markTraceDecorated(target: object): void;
+declare function isTraceIgnored(method?: object, type?: object): boolean;
+declare function isTraceDecorated(method?: object): boolean;
+
+interface TraceOptions {
+    name?: string;
+    attributes?: Record<string, string>;
+}
+type TraceDecorator = MethodDecorator & ClassDecorator;
+declare function Trace(nameOrOptions?: string | TraceOptions): TraceDecorator;
+
+interface StructuredLogRecord {
+    body: unknown;
+    severityText: 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'FATAL';
+    attributes: Attributes;
+    timestamp?: number;
+}
+interface StructuredLogEmitter {
+    emit(record: StructuredLogRecord): void;
+}
+
+declare class NestLoggerInstrumentation {
+    private readonly emitter;
+    private readonly resourceAttributes;
+    private originals;
+    private enabled;
+    constructor(emitter: StructuredLogEmitter, resourceAttributes?: Record<string, string>);
+    enable(): void;
+    disable(): void;
+}
+
+declare class OpenTelemetryLogEmitter implements StructuredLogEmitter {
+    private readonly logger;
+    constructor(name?: string, version?: string, logger?: Logger);
+    emit(record: StructuredLogRecord): void;
+}
+
+interface CompatibleNestInstrumentationConfig extends InstrumentationConfig {
+    providerTracing?: boolean;
+    controllerTracing?: boolean;
+}
+/** Extends upstream Nest support to v12 and instruments DI-created providers. */
+declare class CompatibleNestInstrumentation extends NestInstrumentation {
+    private readonly observeConfig;
+    private methodInstrumenter?;
+    constructor(observeConfig?: CompatibleNestInstrumentationConfig);
+    init(): InstrumentationNodeModuleDefinition;
+    private getMethodInstrumenter;
+}
+
+declare class HttpRequestMetrics {
+    private readonly serviceName;
+    private readonly requestCount;
+    private readonly requestDuration;
+    private readonly errorCount;
+    private readonly startedAt;
+    constructor(meter: Meter, serviceName: string);
+    start(request: IncomingMessage): void;
+    record(request: IncomingMessage, response: ServerResponse): void;
+}
+
+declare class RuntimeMetrics {
+    private readonly meter;
+    private readonly callbacks;
+    private eventLoopDelay;
+    private gcObserver;
+    private started;
+    private previousElu;
+    constructor(meter: Meter);
+    private observe;
+    start(): void;
+    stop(): void;
+}
+
+type NestComponentKind = 'provider' | 'controller';
+declare class NestMethodInstrumenter {
+    private readonly tracer;
+    private readonly calls;
+    private readonly duration;
+    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;
+    private instrumentTarget;
+}
+
+declare const OBSERVE_OPTIONS: unique symbol;
+declare const OBSERVE_HANDLE: unique symbol;
+declare class ObserveModule {
+    static forRoot(options?: ObserveOptions): DynamicModule;
+}
+
+declare const SDK_NAME = "@ryanzen9/nest-observe";
+declare const SDK_VERSION = "0.1.0";
+declare function createObserveResource(config: ResolvedObserveConfig): Resource;
+
+declare const REDACTED = "[REDACTED]";
+declare function isSensitiveKey(name: string): boolean;
+declare function redactText(value: string): string;
+declare function redact<T>(value: T): T;
+declare function sanitizeHeaders(headers: Record<string, string | string[] | undefined>, allowedHeaders: readonly string[]): Record<string, string>;
+
+/** Last-line protection for spans emitted by third-party instrumentation. */
+declare class SpanRedactionProcessor implements SpanProcessor {
+    onStart(_span: Span, _parentContext: Context): void;
+    onEnd(span: ReadableSpan): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+interface ObserveRuntime extends ObserveHandle {
+    readonly tracerProvider: NodeTracerProvider | undefined;
+    readonly meterProvider: MeterProvider | undefined;
+    readonly loggerProvider: LoggerProvider | undefined;
+}
+declare function observe(options?: ObserveOptions): ObserveRuntime;
+declare function getObserveRuntime(): ObserveRuntime | undefined;
+
+export { CompatibleNestInstrumentation, type CompatibleNestInstrumentationConfig, HttpRequestMetrics, IgnoreTrace, type NestComponentKind, NestLoggerInstrumentation, NestMethodInstrumenter, OBSERVE_HANDLE, OBSERVE_OPTIONS, type ObserveExporters, type ObserveHandle, ObserveModule, type ObserveOptions, type ObserveRuntime, OpenTelemetryLogEmitter, REDACTED, type ResolvedObserveConfig, RuntimeMetrics, SDK_NAME, SDK_VERSION, SpanRedactionProcessor, type StructuredLogEmitter, type StructuredLogRecord, Trace, type TraceOptions, createObserveResource, getObserveRuntime, isSensitiveKey, isTraceDecorated, isTraceIgnored, markTraceDecorated, markTraceIgnored, observe, parseKeyValueList, redact, redactText, resolveObserveConfig, sanitizeHeaders };

package/dist/index.d.ts

@@ -0,0 +1,197 @@
+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 { InstrumentationConfig, InstrumentationNodeModuleDefinition } from '@opentelemetry/instrumentation';
+import { NestInstrumentation } from '@opentelemetry/instrumentation-nestjs-core';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { DynamicModule } from '@nestjs/common';
+import { Resource } from '@opentelemetry/resources';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+
+interface ObserveExporters {
+    /** Primarily useful for custom backends and tests. OTLP is used by default. */
+    span?: SpanExporter;
+    log?: LogRecordExporter;
+    metricReader?: MetricReader;
+}
+interface ObserveOptions {
+    enabled?: boolean;
+    serviceName?: string;
+    serviceVersion?: string;
+    environment?: string;
+    instanceId?: string;
+    endpoint?: string;
+    headers?: Record<string, string>;
+    traces?: boolean;
+    logs?: boolean;
+    metrics?: boolean;
+    providerTracing?: boolean;
+    controllerTracing?: boolean;
+    sampling?: number;
+    allowedHeaders?: string[];
+    exportTimeoutMillis?: number;
+    metricExportIntervalMillis?: number;
+    resourceAttributes?: Record<string, string | number | boolean>;
+    exporters?: ObserveExporters;
+}
+interface ResolvedObserveConfig {
+    enabled: boolean;
+    serviceName: string;
+    serviceVersion: string;
+    environment: string;
+    instanceId: string;
+    endpoints: {
+        traces: string | undefined;
+        metrics: string | undefined;
+        logs: string | undefined;
+    };
+    headers: Record<string, string>;
+    traces: boolean;
+    logs: boolean;
+    metrics: boolean;
+    providerTracing: boolean;
+    controllerTracing: boolean;
+    sampling: number;
+    allowedHeaders: string[];
+    exportTimeoutMillis: number;
+    metricExportIntervalMillis: number;
+    resourceAttributes: Record<string, string | number | boolean>;
+    exporters?: ObserveExporters;
+}
+interface ObserveHandle {
+    readonly started: boolean;
+    readonly config: Readonly<ResolvedObserveConfig>;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+type Environment = Record<string, string | undefined>;
+declare function parseKeyValueList(value?: string): Record<string, string>;
+declare function resolveObserveConfig(options?: ObserveOptions, env?: Environment): ResolvedObserveConfig;
+
+type IgnoreDecorator = MethodDecorator & ClassDecorator;
+declare function IgnoreTrace(): IgnoreDecorator;
+
+declare function markTraceIgnored(target: object): void;
+declare function markTraceDecorated(target: object): void;
+declare function isTraceIgnored(method?: object, type?: object): boolean;
+declare function isTraceDecorated(method?: object): boolean;
+
+interface TraceOptions {
+    name?: string;
+    attributes?: Record<string, string>;
+}
+type TraceDecorator = MethodDecorator & ClassDecorator;
+declare function Trace(nameOrOptions?: string | TraceOptions): TraceDecorator;
+
+interface StructuredLogRecord {
+    body: unknown;
+    severityText: 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'FATAL';
+    attributes: Attributes;
+    timestamp?: number;
+}
+interface StructuredLogEmitter {
+    emit(record: StructuredLogRecord): void;
+}
+
+declare class NestLoggerInstrumentation {
+    private readonly emitter;
+    private readonly resourceAttributes;
+    private originals;
+    private enabled;
+    constructor(emitter: StructuredLogEmitter, resourceAttributes?: Record<string, string>);
+    enable(): void;
+    disable(): void;
+}
+
+declare class OpenTelemetryLogEmitter implements StructuredLogEmitter {
+    private readonly logger;
+    constructor(name?: string, version?: string, logger?: Logger);
+    emit(record: StructuredLogRecord): void;
+}
+
+interface CompatibleNestInstrumentationConfig extends InstrumentationConfig {
+    providerTracing?: boolean;
+    controllerTracing?: boolean;
+}
+/** Extends upstream Nest support to v12 and instruments DI-created providers. */
+declare class CompatibleNestInstrumentation extends NestInstrumentation {
+    private readonly observeConfig;
+    private methodInstrumenter?;
+    constructor(observeConfig?: CompatibleNestInstrumentationConfig);
+    init(): InstrumentationNodeModuleDefinition;
+    private getMethodInstrumenter;
+}
+
+declare class HttpRequestMetrics {
+    private readonly serviceName;
+    private readonly requestCount;
+    private readonly requestDuration;
+    private readonly errorCount;
+    private readonly startedAt;
+    constructor(meter: Meter, serviceName: string);
+    start(request: IncomingMessage): void;
+    record(request: IncomingMessage, response: ServerResponse): void;
+}
+
+declare class RuntimeMetrics {
+    private readonly meter;
+    private readonly callbacks;
+    private eventLoopDelay;
+    private gcObserver;
+    private started;
+    private previousElu;
+    constructor(meter: Meter);
+    private observe;
+    start(): void;
+    stop(): void;
+}
+
+type NestComponentKind = 'provider' | 'controller';
+declare class NestMethodInstrumenter {
+    private readonly tracer;
+    private readonly calls;
+    private readonly duration;
+    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;
+    private instrumentTarget;
+}
+
+declare const OBSERVE_OPTIONS: unique symbol;
+declare const OBSERVE_HANDLE: unique symbol;
+declare class ObserveModule {
+    static forRoot(options?: ObserveOptions): DynamicModule;
+}
+
+declare const SDK_NAME = "@ryanzen9/nest-observe";
+declare const SDK_VERSION = "0.1.0";
+declare function createObserveResource(config: ResolvedObserveConfig): Resource;
+
+declare const REDACTED = "[REDACTED]";
+declare function isSensitiveKey(name: string): boolean;
+declare function redactText(value: string): string;
+declare function redact<T>(value: T): T;
+declare function sanitizeHeaders(headers: Record<string, string | string[] | undefined>, allowedHeaders: readonly string[]): Record<string, string>;
+
+/** Last-line protection for spans emitted by third-party instrumentation. */
+declare class SpanRedactionProcessor implements SpanProcessor {
+    onStart(_span: Span, _parentContext: Context): void;
+    onEnd(span: ReadableSpan): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+interface ObserveRuntime extends ObserveHandle {
+    readonly tracerProvider: NodeTracerProvider | undefined;
+    readonly meterProvider: MeterProvider | undefined;
+    readonly loggerProvider: LoggerProvider | undefined;
+}
+declare function observe(options?: ObserveOptions): ObserveRuntime;
+declare function getObserveRuntime(): ObserveRuntime | undefined;
+
+export { CompatibleNestInstrumentation, type CompatibleNestInstrumentationConfig, HttpRequestMetrics, IgnoreTrace, type NestComponentKind, NestLoggerInstrumentation, NestMethodInstrumenter, OBSERVE_HANDLE, OBSERVE_OPTIONS, type ObserveExporters, type ObserveHandle, ObserveModule, type ObserveOptions, type ObserveRuntime, OpenTelemetryLogEmitter, REDACTED, type ResolvedObserveConfig, RuntimeMetrics, SDK_NAME, SDK_VERSION, SpanRedactionProcessor, type StructuredLogEmitter, type StructuredLogRecord, Trace, type TraceOptions, createObserveResource, getObserveRuntime, isSensitiveKey, isTraceDecorated, isTraceIgnored, markTraceDecorated, markTraceIgnored, observe, parseKeyValueList, redact, redactText, resolveObserveConfig, sanitizeHeaders };