@ryanzeng/nest-observe 0.1.0 → 0.1.2

package/dist/register.mjs

@@ -91,15 +91,14 @@ function resolveObserveConfig(options = {}, env = process.env) {
     allowedHeaders,
     exportTimeoutMillis: positiveInteger(options.exportTimeoutMillis ?? env.OTEL_EXPORTER_OTLP_TIMEOUT, 1e4),
     metricExportIntervalMillis: positiveInteger(options.metricExportIntervalMillis ?? env.OTEL_METRIC_EXPORT_INTERVAL, 6e4),
-    resourceAttributes
+    resourceAttributes,
+    diagnosticLogging: booleanValue(options.diagnosticLogging, true),
+    failFast: booleanValue(options.failFast, false)
   };
   if (options.exporters) result.exporters = options.exporters;
   return result;
 }
 
-// src/exceptions/process-exception-capture.ts
-import { trace, SpanStatusCode } from "@opentelemetry/api";
-
 // src/security/redaction.ts
 var REDACTED = "[REDACTED]";
 var SENSITIVE_KEY = /(?:authorization|proxy-authorization|cookie|set-cookie|pass(?:word|wd)?|secret|token|api[-_]?key|phone|mobile)/i;
@@ -133,7 +132,115 @@ function redact(value) {
   return visit(value, /* @__PURE__ */ new WeakSet());
 }
 
+// src/diagnostics.ts
+function toError(value) {
+  if (value instanceof Error) return value;
+  if (typeof value === "string") return new Error(value);
+  try {
+    return new Error(JSON.stringify(value));
+  } catch {
+    return new Error(String(value));
+  }
+}
+function sanitizeError(error) {
+  const sanitized = new Error(redactText(error.message));
+  sanitized.name = error.name;
+  if (error.stack) sanitized.stack = redactText(error.stack);
+  return sanitized;
+}
+var ObserveDiagnostics = class {
+  constructor(logging, onError) {
+    this.logging = logging;
+    this.onError = onError;
+  }
+  logging;
+  onError;
+  currentStatus = "starting";
+  currentError;
+  failedSignals = /* @__PURE__ */ new Set();
+  reported = /* @__PURE__ */ new Set();
+  get status() {
+    return this.currentStatus;
+  }
+  get lastError() {
+    return this.currentError;
+  }
+  activate() {
+    if (this.currentStatus === "starting") this.currentStatus = "active";
+  }
+  inactive() {
+    this.currentStatus = "inactive";
+  }
+  stop() {
+    this.currentStatus = "stopped";
+  }
+  success(signal) {
+    this.failedSignals.delete(signal);
+    for (const fingerprint of this.reported) {
+      if (fingerprint.startsWith(`${signal}\0`)) this.reported.delete(fingerprint);
+    }
+    if (this.currentStatus === "degraded" && this.failedSignals.size === 0) {
+      this.currentStatus = "active";
+    }
+  }
+  failure(signal, stage, value) {
+    const error = sanitizeError(toError(value));
+    const event = { signal, stage, error, timestamp: Date.now() };
+    this.currentError = event;
+    this.failedSignals.add(signal);
+    if (this.currentStatus !== "inactive" && this.currentStatus !== "stopped") {
+      this.currentStatus = "degraded";
+    }
+    const fingerprint = `${signal}\0${stage}\0${error.name}\0${error.message}`;
+    if (this.reported.has(fingerprint)) return;
+    this.reported.add(fingerprint);
+    try {
+      this.onError?.(event);
+    } catch {
+    }
+    if (!this.logging) return;
+    try {
+      process.stderr.write(
+        `[nest-observe] ${signal} ${stage} failed: ${redactText(error.message)}
+`
+      );
+    } catch {
+    }
+  }
+};
+function withExporterDiagnostics(exporter, signal, diagnostics) {
+  const delegate = exporter;
+  return new Proxy(exporter, {
+    get(target, property) {
+      if (property === "export") {
+        return (items, callback) => {
+          try {
+            delegate.export.call(target, items, (result) => {
+              if (result.code === 0) {
+                diagnostics.success(signal);
+              } else {
+                diagnostics.failure(
+                  signal,
+                  "export",
+                  result.error ?? new Error(`${signal} export failed`)
+                );
+              }
+              callback(result);
+            });
+          } catch (error) {
+            diagnostics.failure(signal, "export", error);
+            throw error;
+          }
+        };
+      }
+      const value = Reflect.get(target, property, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    }
+  });
+}
+
 // src/exceptions/process-exception-capture.ts
+import { trace, SpanStatusCode } from "@opentelemetry/api";
 function asError(value) {
   return value instanceof Error ? value : new Error(String(value));
 }
@@ -387,7 +494,13 @@ var SEVERITY = {
 };
 function bodyValue(message) {
   if (message instanceof Error) return redactText(message.stack ?? `${message.name}: ${message.message}`);
-  return redact(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));
+  }
 }
 var NestLoggerInstrumentation = class {
   constructor(emitter, resourceAttributes = {}) {
@@ -450,7 +563,7 @@ var SEVERITY_NUMBER = {
 };
 var OpenTelemetryLogEmitter = class {
   logger;
-  constructor(name = "@ryanzen9/nest-observe", version, logger) {
+  constructor(name = "@ryanzeng/nest-observe", version, logger) {
     this.logger = logger ?? logs.getLogger(name, version);
   }
   emit(record) {
@@ -494,9 +607,14 @@ var HttpRequestMetrics = class {
   errorCount;
   startedAt = /* @__PURE__ */ new WeakMap();
   start(request) {
+    if (this.startedAt.has(request)) return false;
     this.startedAt.set(request, process.hrtime.bigint());
+    return true;
   }
   record(request, response) {
+    const started = this.startedAt.get(request);
+    if (started === void 0) return false;
+    this.startedAt.delete(request);
     const statusCode = Number.isFinite(response.statusCode) ? response.statusCode : 0;
     const attributes = {
       "service.name": this.serviceName,
@@ -505,12 +623,9 @@ var HttpRequestMetrics = class {
       "http.response.status_code": statusCode
     };
     this.requestCount.add(1, attributes);
-    const started = this.startedAt.get(request);
-    if (started !== void 0) {
-      this.requestDuration.record(Number(process.hrtime.bigint() - started) / 1e9, attributes);
-      this.startedAt.delete(request);
-    }
+    this.requestDuration.record(Number(process.hrtime.bigint() - started) / 1e9, attributes);
     if (statusCode >= 500) this.errorCount.add(1, attributes);
+    return true;
   }
 };
 
@@ -596,21 +711,136 @@ var RuntimeMetrics = class {
 };
 
 // src/resource.ts
+import {
+  defaultResource,
+  resourceFromAttributes
+} from "@opentelemetry/resources";
 import { hostname } from "os";
-import { defaultResource, resourceFromAttributes } from "@opentelemetry/resources";
-var SDK_NAME = "@ryanzen9/nest-observe";
-var SDK_VERSION = "0.1.0";
+
+// package.json
+var package_default = {
+  name: "@ryanzeng/nest-observe",
+  version: "0.1.2",
+  description: "Zero-config, vendor-neutral OpenTelemetry observability for NestJS",
+  keywords: [
+    "nestjs",
+    "opentelemetry",
+    "observability",
+    "otlp",
+    "tracing",
+    "metrics",
+    "logging"
+  ],
+  license: "MIT",
+  homepage: "https://github.com/ryanzen9/nest-observe#readme",
+  bugs: {
+    url: "https://github.com/ryanzen9/nest-observe/issues"
+  },
+  repository: {
+    type: "git",
+    url: "git+https://github.com/ryanzen9/nest-observe.git"
+  },
+  packageManager: "pnpm@10.13.1",
+  sideEffects: [
+    "./dist/register.js",
+    "./dist/register.mjs"
+  ],
+  main: "./dist/index.js",
+  module: "./dist/index.mjs",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      import: {
+        types: "./dist/index.d.mts",
+        default: "./dist/index.mjs"
+      },
+      require: {
+        types: "./dist/index.d.ts",
+        default: "./dist/index.js"
+      }
+    },
+    "./register": {
+      import: {
+        types: "./dist/register.d.mts",
+        default: "./dist/register.mjs"
+      },
+      require: {
+        types: "./dist/register.d.ts",
+        default: "./dist/register.js"
+      }
+    }
+  },
+  files: [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  scripts: {
+    build: "tsup",
+    test: "vitest run",
+    "test:watch": "vitest",
+    typecheck: "tsc --noEmit",
+    check: "pnpm typecheck && pnpm test && pnpm build"
+  },
+  engines: {
+    node: ">=20"
+  },
+  peerDependencies: {
+    "@nestjs/common": ">=10 <13",
+    "@nestjs/core": ">=10 <13",
+    "reflect-metadata": ">=0.1.12 <1",
+    rxjs: "^7.1.0"
+  },
+  dependencies: {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/api-logs": "^0.221.0",
+    "@opentelemetry/exporter-logs-otlp-proto": "^0.221.0",
+    "@opentelemetry/exporter-metrics-otlp-proto": "^0.221.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.221.0",
+    "@opentelemetry/instrumentation": "^0.221.0",
+    "@opentelemetry/instrumentation-http": "^0.221.0",
+    "@opentelemetry/instrumentation-nestjs-core": "^0.67.0",
+    "@opentelemetry/resources": "^2.10.0",
+    "@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"
+  },
+  devDependencies: {
+    "@nestjs/common": "^12.0.1",
+    "@nestjs/core": "^12.0.1",
+    "@nestjs/testing": "^12.0.1",
+    "@opentelemetry/sdk-trace-base": "^2.10.0",
+    "@types/node": "^24.0.0",
+    "reflect-metadata": "^0.2.2",
+    rxjs: "^7.8.2",
+    tsup: "^8.5.1",
+    typescript: "^5.9.3",
+    vitest: "^4.1.11"
+  },
+  publishConfig: {
+    access: "public"
+  }
+};
+
+// src/resource.ts
+var SDK_NAME = package_default.name;
+var SDK_VERSION = package_default.version;
 function createObserveResource(config) {
-  return defaultResource().merge(resourceFromAttributes({
-    ...config.resourceAttributes,
-    "service.name": config.serviceName,
-    "service.version": config.serviceVersion,
-    "deployment.environment.name": config.environment,
-    "service.instance.id": config.instanceId,
-    "telemetry.sdk.name": SDK_NAME,
-    "telemetry.sdk.version": SDK_VERSION,
-    "host.name": config.resourceAttributes["host.name"] ?? hostname()
-  }));
+  return defaultResource().merge(
+    resourceFromAttributes({
+      ...config.resourceAttributes,
+      "service.name": config.serviceName,
+      "service.version": config.serviceVersion,
+      "deployment.environment.name": config.environment,
+      "service.instance.id": config.instanceId,
+      "telemetry.sdk.name": SDK_NAME,
+      "telemetry.sdk.version": SDK_VERSION,
+      "host.name": config.resourceAttributes["host.name"] ?? hostname()
+    })
+  );
 }
 
 // src/security/span-redaction-processor.ts
@@ -654,14 +884,23 @@ var SpanRedactionProcessor = class {
 
 // src/sdk.ts
 var InactiveObserveHandle = class {
-  constructor(config) {
+  constructor(config, diagnostics) {
     this.config = config;
+    this.diagnostics = diagnostics;
   }
   config;
+  diagnostics;
   started = false;
   tracerProvider = void 0;
   meterProvider = void 0;
   loggerProvider = void 0;
+  httpRequestMetrics = void 0;
+  get status() {
+    return this.diagnostics.status;
+  }
+  get lastError() {
+    return this.diagnostics.lastError;
+  }
   forceFlush() {
     return Promise.resolve();
   }
@@ -670,52 +909,73 @@ var InactiveObserveHandle = class {
   }
 };
 var ActiveObserveHandle = class {
-  constructor(config, tracerProvider, meterProvider, loggerProvider, runtimeMetrics, loggerInstrumentation, exceptionCapture, instrumentations) {
+  constructor(config, tracerProvider, meterProvider, loggerProvider, httpRequestMetrics, runtimeMetrics, loggerInstrumentation, exceptionCapture, instrumentations, diagnostics) {
     this.config = config;
     this.tracerProvider = tracerProvider;
     this.meterProvider = meterProvider;
     this.loggerProvider = loggerProvider;
+    this.httpRequestMetrics = httpRequestMetrics;
     this.runtimeMetrics = runtimeMetrics;
     this.loggerInstrumentation = loggerInstrumentation;
     this.exceptionCapture = exceptionCapture;
     this.instrumentations = instrumentations;
+    this.diagnostics = diagnostics;
   }
   config;
   tracerProvider;
   meterProvider;
   loggerProvider;
+  httpRequestMetrics;
   runtimeMetrics;
   loggerInstrumentation;
   exceptionCapture;
   instrumentations;
+  diagnostics;
   started = true;
   stopped = false;
+  get status() {
+    return this.diagnostics.status;
+  }
+  get lastError() {
+    return this.diagnostics.lastError;
+  }
   async forceFlush() {
-    await Promise.allSettled([
-      this.tracerProvider?.forceFlush(),
-      this.meterProvider?.forceFlush(),
-      this.loggerProvider?.forceFlush({ timeoutMillis: this.config.exportTimeoutMillis })
-    ].filter((item) => Boolean(item)));
+    await this.runSafely("forceFlush", [
+      ...this.config.traces && this.tracerProvider ? [["traces", () => this.tracerProvider.forceFlush()]] : [],
+      ...this.config.metrics && this.meterProvider ? [["metrics", () => this.meterProvider.forceFlush()]] : [],
+      ...this.config.logs && this.loggerProvider ? [["logs", () => this.loggerProvider.forceFlush({ timeoutMillis: this.config.exportTimeoutMillis })]] : []
+    ]);
   }
   async shutdown() {
     if (this.stopped) return;
     this.stopped = true;
     this.loggerInstrumentation?.disable();
-    this.runtimeMetrics?.stop();
     this.exceptionCapture.stop();
     for (const instrumentation of this.instrumentations) {
       try {
         instrumentation.disable();
-      } catch {
+      } catch (error) {
+        this.diagnostics.failure("sdk", "shutdown", error);
       }
     }
     await this.forceFlush();
-    await Promise.allSettled([
-      this.tracerProvider?.shutdown(),
-      this.meterProvider?.shutdown(),
-      this.loggerProvider?.shutdown()
-    ].filter((item) => Boolean(item)));
+    this.runtimeMetrics?.stop();
+    await this.runSafely("shutdown", [
+      ...this.tracerProvider ? [["traces", () => this.tracerProvider.shutdown()]] : [],
+      ...this.meterProvider ? [["metrics", () => this.meterProvider.shutdown()]] : [],
+      ...this.loggerProvider ? [["logs", () => this.loggerProvider.shutdown()]] : []
+    ]);
     if (activeRuntime === this) activeRuntime = void 0;
+    this.diagnostics.stop();
+  }
+  async runSafely(stage, operations) {
+    await Promise.all(operations.map(async ([signal, operation]) => {
+      try {
+        await operation();
+      } catch (error) {
+        this.diagnostics.failure(signal, stage, error);
+      }
+    }));
   }
 };
 var activeRuntime;
@@ -726,12 +986,16 @@ function exporterConfig(url, config) {
     timeoutMillis: config.exportTimeoutMillis
   };
 }
-function createTraceProvider(config, resource) {
+function createTraceProvider(config, resource, diagnostics) {
   if (!config.traces && !config.metrics) return void 0;
   const spanProcessors = [new SpanRedactionProcessor()];
   if (config.traces) {
     const exporter = config.exporters?.span ?? new OTLPTraceExporter(exporterConfig(config.endpoints.traces, config));
-    spanProcessors.push(new BatchSpanProcessor(exporter, {
+    spanProcessors.push(new BatchSpanProcessor(withExporterDiagnostics(
+      exporter,
+      "traces",
+      diagnostics
+    ), {
       exportTimeoutMillis: config.exportTimeoutMillis,
       maxQueueSize: 2048,
       maxExportBatchSize: 512
@@ -746,14 +1010,18 @@ function createTraceProvider(config, resource) {
   provider.register();
   return provider;
 }
-function createMeterProvider(config, resource) {
+function createMeterProvider(config, resource, diagnostics) {
   if (!config.metrics) return void 0;
   let reader;
   if (config.exporters?.metricReader) {
     reader = config.exporters.metricReader;
   } else {
     reader = new PeriodicExportingMetricReader({
-      exporter: new OTLPMetricExporter(exporterConfig(config.endpoints.metrics, config)),
+      exporter: withExporterDiagnostics(
+        new OTLPMetricExporter(exporterConfig(config.endpoints.metrics, config)),
+        "metrics",
+        diagnostics
+      ),
       exportIntervalMillis: config.metricExportIntervalMillis,
       exportTimeoutMillis: Math.min(config.exportTimeoutMillis, config.metricExportIntervalMillis),
       cardinalityLimits: { default: 2e3, histogram: 2e3 }
@@ -771,13 +1039,13 @@ function createMeterProvider(config, resource) {
   metrics.setGlobalMeterProvider(provider);
   return provider;
 }
-function createLoggerProvider(config, resource) {
+function createLoggerProvider(config, resource, diagnostics) {
   if (!config.logs) return void 0;
   const exporter = config.exporters?.log ?? new OTLPLogExporter(exporterConfig(config.endpoints.logs, config));
   const provider = new LoggerProvider({
     resource,
     processors: [new BatchLogRecordProcessor({
-      exporter,
+      exporter: withExporterDiagnostics(exporter, "logs", diagnostics),
       exportTimeoutMillis: config.exportTimeoutMillis,
       maxQueueSize: 2048,
       maxExportBatchSize: 512
@@ -789,7 +1057,11 @@ function createLoggerProvider(config, resource) {
 function observe(options = {}) {
   if (activeRuntime?.started) return activeRuntime;
   const config = resolveObserveConfig(options);
-  if (!config.enabled) return new InactiveObserveHandle(config);
+  const diagnostics = new ObserveDiagnostics(config.diagnosticLogging, options.onError);
+  if (!config.enabled) {
+    diagnostics.inactive();
+    return new InactiveObserveHandle(config, diagnostics);
+  }
   let tracerProvider;
   let meterProvider;
   let loggerProvider;
@@ -799,10 +1071,11 @@ function observe(options = {}) {
   const instrumentations = [];
   try {
     const resource = createObserveResource(config);
-    meterProvider = createMeterProvider(config, resource);
+    meterProvider = createMeterProvider(config, resource, diagnostics);
     const meter = meterProvider?.getMeter(SDK_NAME, SDK_VERSION);
-    tracerProvider = createTraceProvider(config, resource);
-    loggerProvider = createLoggerProvider(config, resource);
+    const httpRequestMetrics = meter ? new HttpRequestMetrics(meter, config.serviceName) : void 0;
+    tracerProvider = createTraceProvider(config, resource, diagnostics);
+    loggerProvider = createLoggerProvider(config, resource, diagnostics);
     runtimeMetrics = meter ? new RuntimeMetrics(meter) : void 0;
     runtimeMetrics?.start();
     const otelLogger = loggerProvider?.getLogger(SDK_NAME, SDK_VERSION);
@@ -817,7 +1090,6 @@ function observe(options = {}) {
     exceptionCapture.start();
     if (config.traces || config.metrics) {
       const safeHeaders = config.allowedHeaders.filter((header) => !isSensitiveKey(header));
-      const httpRequestMetrics = meter ? new HttpRequestMetrics(meter, config.serviceName) : void 0;
       instrumentations.push(new HttpInstrumentation({
         requireParentforOutgoingSpans: false,
         headersToSpanAttributes: {
@@ -861,14 +1133,18 @@ function observe(options = {}) {
       tracerProvider,
       meterProvider,
       loggerProvider,
+      httpRequestMetrics,
       runtimeMetrics,
       loggerInstrumentation,
       exceptionCapture,
-      instrumentations
+      instrumentations,
+      diagnostics
     );
+    diagnostics.activate();
     activeRuntime = runtime;
     return runtime;
-  } catch {
+  } catch (error) {
+    diagnostics.failure("sdk", "initialization", error);
     loggerInstrumentation?.disable();
     runtimeMetrics?.stop();
     exceptionCapture?.stop();
@@ -883,7 +1159,9 @@ function observe(options = {}) {
       meterProvider?.shutdown(),
       loggerProvider?.shutdown()
     ].filter((item) => Boolean(item)));
-    return new InactiveObserveHandle(config);
+    diagnostics.inactive();
+    if (config.failFast) throw toError(error);
+    return new InactiveObserveHandle(config, diagnostics);
   }
 }