@ryanzeng/nest-observe 0.1.1 → 0.1.2

package/README.md

@@ -36,7 +36,7 @@ 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，不会阻止业务应用启动。
+初始化或 exporter 配置失败时，SDK 默认保持 fail-open，不会阻止业务应用启动；同时会把脱敏、限频后的诊断信息写入 `stderr`，避免观测链路静默失效。
 
 ## OpenObserve 完整示例
 
@@ -56,6 +56,8 @@ import { ObserveModule } from '@ryanzeng/nest-observe';
 export class AppModule {}
 ```
 
+Module-only 模式还会注册一个全局 Nest interceptor，补采因 HTTP 模块已经加载而无法挂载底层 hook 的已匹配 Controller 请求指标。它与早期 HTTP instrumentation 共享请求状态，不会重复计数。
+
 ## 装饰器
 
 ```ts
@@ -95,6 +97,7 @@ Traces：
 Logs：
 
 - 默认 Nest `Logger` 的 `verbose/debug/log/warn/error/fatal`
+- 对象和数组消息会在脱敏后序列化成 JSON 字符串，保证 OpenObserve 的标准 `body` 字段始终可见
 - OTLP severity、`nestjs.context`、`trace_id`、`span_id`
 - `service.name`、`service.version`、`deployment.environment.name`
 - `StructuredLogEmitter` 抽象可用于后续 Pino/Winston adapter
@@ -110,6 +113,8 @@ Metrics：
 
 HTTP 与 Nest method 指标只使用 route template、method、status、controller/provider/method 等有限维度，避免把 URL id 或请求数据变成高基数标签。
 
+OpenObserve 会把 OTel metric 名称中的 `.` 转换为 `_`，例如 `process.uptime` 对应 `process_uptime` stream，`http.server.request.count` 对应 `http_server_request_count`。指标使用独立的 Metrics streams，不在 Logs 的 `default` stream 中；首次数据默认最多需要等待 `metricExportIntervalMillis`（默认 60 秒），也可以调用 `forceFlush()` 立即导出。应用关闭时 SDK 会先采集并 flush runtime observable metrics，再移除 callbacks。
+
 ## 程序化配置
 
 ```ts
@@ -134,6 +139,27 @@ await telemetry.shutdown();
 
 环境变量方式仍是推荐方式。有合理默认值的配置无需填写。
 
+### 故障诊断
+
+SDK 会区分本地 pipeline 已启动和远端导出是否健康。`status` 可能为 `inactive`、`starting`、`active`、`degraded` 或 `stopped`；例如 OTLP endpoint 返回 401 时，业务继续运行，但状态会变为 `degraded`：
+
+```ts
+const telemetry = observe({
+  serviceName: 'mall-app',
+  endpoint: 'https://observe.example.com',
+  onError(event) {
+    // event.error 已脱敏，不包含 Authorization、token 等凭据。
+    console.error(event.signal, event.stage, event.error.message);
+  },
+});
+
+console.log(telemetry.status, telemetry.lastError);
+```
+
+默认诊断日志直接写入原始 `stderr`，不会经过 Nest Logger，因而不会形成“导出失败日志再次导出”的递归。相同错误在恢复前只报告一次。可以设置 `diagnosticLogging: false` 关闭默认输出，并继续通过 `onError` 接收事件。
+
+同步初始化失败默认返回 `started: false`、`status: 'inactive'` 的 handle。测试或严格部署场景可以设置 `failFast: true`，让同步初始化错误直接阻止 Nest 启动；异步 OTLP 导出错误仍采用 fail-open，并通过 `degraded`、`lastError` 和 `onError` 暴露。
+
 ### Sampling
 
 支持显式 `sampling`（0–1）以及标准环境变量：

package/dist/index.d.mts

@@ -6,9 +6,10 @@ 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 { NestInterceptor, ExecutionContext, CallHandler, DynamicModule } from '@nestjs/common';
+import { Observable } from 'rxjs';
 import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { Resource } from '@opentelemetry/resources';
 
 interface ObserveExporters {
     /** Primarily useful for custom backends and tests. OTLP is used by default. */
@@ -16,6 +17,15 @@ interface ObserveExporters {
     log?: LogRecordExporter;
     metricReader?: MetricReader;
 }
+type ObserveSignal = 'sdk' | 'traces' | 'metrics' | 'logs';
+type ObserveErrorStage = 'initialization' | 'export' | 'forceFlush' | 'shutdown';
+type ObserveStatus = 'inactive' | 'starting' | 'active' | 'degraded' | 'stopped';
+interface ObserveErrorEvent {
+    signal: ObserveSignal;
+    stage: ObserveErrorStage;
+    error: Error;
+    timestamp: number;
+}
 interface ObserveOptions {
     enabled?: boolean;
     serviceName?: string;
@@ -34,6 +44,12 @@ interface ObserveOptions {
     exportTimeoutMillis?: number;
     metricExportIntervalMillis?: number;
     resourceAttributes?: Record<string, string | number | boolean>;
+    /** Writes sanitized, rate-limited SDK/export failures to stderr. Defaults to true. */
+    diagnosticLogging?: boolean;
+    /** Receives sanitized pipeline failure notifications without affecting the application. */
+    onError?: (event: ObserveErrorEvent) => void;
+    /** Throws synchronous initialization failures instead of degrading to an inactive handle. */
+    failFast?: boolean;
     exporters?: ObserveExporters;
 }
 interface ResolvedObserveConfig {
@@ -58,10 +74,14 @@ interface ResolvedObserveConfig {
     exportTimeoutMillis: number;
     metricExportIntervalMillis: number;
     resourceAttributes: Record<string, string | number | boolean>;
+    diagnosticLogging: boolean;
+    failFast: boolean;
     exporters?: ObserveExporters;
 }
 interface ObserveHandle {
     readonly started: boolean;
+    readonly status: ObserveStatus;
+    readonly lastError: ObserveErrorEvent | undefined;
     readonly config: Readonly<ResolvedObserveConfig>;
     forceFlush(): Promise<void>;
     shutdown(): Promise<void>;
@@ -132,8 +152,8 @@ declare class HttpRequestMetrics {
     private readonly errorCount;
     private readonly startedAt;
     constructor(meter: Meter, serviceName: string);
-    start(request: IncomingMessage): void;
-    record(request: IncomingMessage, response: ServerResponse): void;
+    start(request: IncomingMessage): boolean;
+    record(request: IncomingMessage, response: ServerResponse): boolean;
 }
 
 declare class RuntimeMetrics {
@@ -162,14 +182,29 @@ declare class NestMethodInstrumenter {
     private instrumentTarget;
 }
 
+interface ObserveRuntime extends ObserveHandle {
+    readonly tracerProvider: NodeTracerProvider | undefined;
+    readonly meterProvider: MeterProvider | undefined;
+    readonly loggerProvider: LoggerProvider | undefined;
+    readonly httpRequestMetrics: HttpRequestMetrics | undefined;
+}
+declare function observe(options?: ObserveOptions): ObserveRuntime;
+declare function getObserveRuntime(): ObserveRuntime | undefined;
+
 declare const OBSERVE_OPTIONS: unique symbol;
 declare const OBSERVE_HANDLE: unique symbol;
+/** Provides inbound HTTP metrics when module-load instrumentation was registered too late. */
+declare class NestHttpMetricsInterceptor implements NestInterceptor {
+    private readonly handle;
+    constructor(handle: ObserveRuntime);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
 declare class ObserveModule {
     static forRoot(options?: ObserveOptions): DynamicModule;
 }
 
-declare const SDK_NAME = "@ryanzeng/nest-observe";
-declare const SDK_VERSION = "0.1.0";
+declare const SDK_NAME: string;
+declare const SDK_VERSION: string;
 declare function createObserveResource(config: ResolvedObserveConfig): Resource;
 
 declare const REDACTED = "[REDACTED]";
@@ -186,12 +221,4 @@ declare class SpanRedactionProcessor implements SpanProcessor {
     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 };
+export { CompatibleNestInstrumentation, type CompatibleNestInstrumentationConfig, HttpRequestMetrics, IgnoreTrace, type NestComponentKind, NestHttpMetricsInterceptor, NestLoggerInstrumentation, NestMethodInstrumenter, OBSERVE_HANDLE, OBSERVE_OPTIONS, type ObserveErrorEvent, type ObserveErrorStage, type ObserveExporters, type ObserveHandle, ObserveModule, type ObserveOptions, type ObserveRuntime, type ObserveSignal, type ObserveStatus, 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

@@ -6,9 +6,10 @@ 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 { NestInterceptor, ExecutionContext, CallHandler, DynamicModule } from '@nestjs/common';
+import { Observable } from 'rxjs';
 import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { Resource } from '@opentelemetry/resources';
 
 interface ObserveExporters {
     /** Primarily useful for custom backends and tests. OTLP is used by default. */
@@ -16,6 +17,15 @@ interface ObserveExporters {
     log?: LogRecordExporter;
     metricReader?: MetricReader;
 }
+type ObserveSignal = 'sdk' | 'traces' | 'metrics' | 'logs';
+type ObserveErrorStage = 'initialization' | 'export' | 'forceFlush' | 'shutdown';
+type ObserveStatus = 'inactive' | 'starting' | 'active' | 'degraded' | 'stopped';
+interface ObserveErrorEvent {
+    signal: ObserveSignal;
+    stage: ObserveErrorStage;
+    error: Error;
+    timestamp: number;
+}
 interface ObserveOptions {
     enabled?: boolean;
     serviceName?: string;
@@ -34,6 +44,12 @@ interface ObserveOptions {
     exportTimeoutMillis?: number;
     metricExportIntervalMillis?: number;
     resourceAttributes?: Record<string, string | number | boolean>;
+    /** Writes sanitized, rate-limited SDK/export failures to stderr. Defaults to true. */
+    diagnosticLogging?: boolean;
+    /** Receives sanitized pipeline failure notifications without affecting the application. */
+    onError?: (event: ObserveErrorEvent) => void;
+    /** Throws synchronous initialization failures instead of degrading to an inactive handle. */
+    failFast?: boolean;
     exporters?: ObserveExporters;
 }
 interface ResolvedObserveConfig {
@@ -58,10 +74,14 @@ interface ResolvedObserveConfig {
     exportTimeoutMillis: number;
     metricExportIntervalMillis: number;
     resourceAttributes: Record<string, string | number | boolean>;
+    diagnosticLogging: boolean;
+    failFast: boolean;
     exporters?: ObserveExporters;
 }
 interface ObserveHandle {
     readonly started: boolean;
+    readonly status: ObserveStatus;
+    readonly lastError: ObserveErrorEvent | undefined;
     readonly config: Readonly<ResolvedObserveConfig>;
     forceFlush(): Promise<void>;
     shutdown(): Promise<void>;
@@ -132,8 +152,8 @@ declare class HttpRequestMetrics {
     private readonly errorCount;
     private readonly startedAt;
     constructor(meter: Meter, serviceName: string);
-    start(request: IncomingMessage): void;
-    record(request: IncomingMessage, response: ServerResponse): void;
+    start(request: IncomingMessage): boolean;
+    record(request: IncomingMessage, response: ServerResponse): boolean;
 }
 
 declare class RuntimeMetrics {
@@ -162,14 +182,29 @@ declare class NestMethodInstrumenter {
     private instrumentTarget;
 }
 
+interface ObserveRuntime extends ObserveHandle {
+    readonly tracerProvider: NodeTracerProvider | undefined;
+    readonly meterProvider: MeterProvider | undefined;
+    readonly loggerProvider: LoggerProvider | undefined;
+    readonly httpRequestMetrics: HttpRequestMetrics | undefined;
+}
+declare function observe(options?: ObserveOptions): ObserveRuntime;
+declare function getObserveRuntime(): ObserveRuntime | undefined;
+
 declare const OBSERVE_OPTIONS: unique symbol;
 declare const OBSERVE_HANDLE: unique symbol;
+/** Provides inbound HTTP metrics when module-load instrumentation was registered too late. */
+declare class NestHttpMetricsInterceptor implements NestInterceptor {
+    private readonly handle;
+    constructor(handle: ObserveRuntime);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
 declare class ObserveModule {
     static forRoot(options?: ObserveOptions): DynamicModule;
 }
 
-declare const SDK_NAME = "@ryanzeng/nest-observe";
-declare const SDK_VERSION = "0.1.0";
+declare const SDK_NAME: string;
+declare const SDK_VERSION: string;
 declare function createObserveResource(config: ResolvedObserveConfig): Resource;
 
 declare const REDACTED = "[REDACTED]";
@@ -186,12 +221,4 @@ declare class SpanRedactionProcessor implements SpanProcessor {
     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 };
+export { CompatibleNestInstrumentation, type CompatibleNestInstrumentationConfig, HttpRequestMetrics, IgnoreTrace, type NestComponentKind, NestHttpMetricsInterceptor, NestLoggerInstrumentation, NestMethodInstrumenter, OBSERVE_HANDLE, OBSERVE_OPTIONS, type ObserveErrorEvent, type ObserveErrorStage, type ObserveExporters, type ObserveHandle, ObserveModule, type ObserveOptions, type ObserveRuntime, type ObserveSignal, type ObserveStatus, 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 };