@backendkit-labs/observability 0.1.0

package/dist/index.cjs

@@ -0,0 +1,592 @@
+'use strict';
+
+var common = require('@nestjs/common');
+var async_hooks = require('async_hooks');
+var crypto = require('crypto');
+var winston = require('winston');
+var TransportStream = require('winston-transport');
+var axios = require('axios');
+var http = require('http');
+var https = require('https');
+var circuitBreaker = require('@backendkit-labs/circuit-breaker');
+var rxjs = require('rxjs');
+var operators = require('rxjs/operators');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var winston__namespace = /*#__PURE__*/_interopNamespace(winston);
+var TransportStream__default = /*#__PURE__*/_interopDefault(TransportStream);
+var axios__default = /*#__PURE__*/_interopDefault(axios);
+var http__namespace = /*#__PURE__*/_interopNamespace(http);
+var https__namespace = /*#__PURE__*/_interopNamespace(https);
+
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (decorator(result)) || result;
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/internal/otel.ts
+var otel = null;
+try {
+  otel = __require("@opentelemetry/api");
+} catch {
+}
+var getTracer = (name) => otel?.trace?.getTracer(name) ?? noopTracer;
+var getActiveSpan = () => otel ? otel.trace.getSpan(otel.context.active()) : void 0;
+var runInOtelContext = async (span, fn) => {
+  if (!otel || !span) return fn();
+  return otel.context.with(otel.trace.setSpan(otel.context.active(), span), fn);
+};
+var noopSpan = {
+  end: () => {
+  },
+  setAttribute: () => {
+  },
+  setAttributes: () => {
+  },
+  recordException: () => {
+  },
+  setStatus: () => {
+  },
+  spanContext: () => ({ traceId: "", spanId: "" })
+};
+var noopTracer = {
+  startSpan: () => noopSpan,
+  startActiveSpan: (_name, fn) => fn(noopSpan)
+};
+
+// src/correlation/correlation.service.ts
+var storage = new async_hooks.AsyncLocalStorage();
+exports.CorrelationIdService = class CorrelationIdService {
+  /**
+   * Run `fn` inside a context that carries `correlationId`.
+   * All code executed within `fn` (including async continuations) can call
+   * `get()` and receive the same ID without passing it explicitly.
+   */
+  run(correlationId, fn) {
+    return storage.run(correlationId, fn);
+  }
+  /** Current correlation ID, or a fresh UUID when called outside a context. */
+  get() {
+    return storage.getStore() ?? crypto.randomUUID();
+  }
+  /**
+   * Current correlation ID, or `undefined` when called outside a context.
+   * Prefer `get()` for logging; use this only when you need to distinguish
+   * "no context" from "context with a random ID".
+   */
+  getOrUndefined() {
+    return storage.getStore();
+  }
+  /**
+   * Active OTel trace + span IDs when @opentelemetry/api is installed and a
+   * span is active; `undefined` otherwise.
+   */
+  getTraceContext() {
+    const span = getActiveSpan();
+    if (!span) return void 0;
+    const ctx = span.spanContext?.();
+    if (!ctx?.traceId) return void 0;
+    return { traceId: ctx.traceId, spanId: ctx.spanId };
+  }
+};
+exports.CorrelationIdService = __decorateClass([
+  common.Injectable()
+], exports.CorrelationIdService);
+
+// src/observability.constants.ts
+var OBSERVABILITY_OPTIONS = "OBSERVABILITY_OPTIONS";
+var TRANSPORT_CB_DEFAULTS = {
+  failureThreshold: 60,
+  slowCallThreshold: 100,
+  slowCallDurationMs: 6e4,
+  minimumCalls: 3,
+  slidingWindowSize: 5,
+  halfOpenMaxCalls: 1,
+  openTimeoutMs: 3e4
+};
+var WinstonHttpTransport = class extends TransportStream__default.default {
+  client;
+  cb;
+  buffer = [];
+  batchSize;
+  maxBufferSize;
+  flushTimer;
+  constructor(opts) {
+    super(opts);
+    this.batchSize = opts.batchSize ?? 100;
+    this.maxBufferSize = opts.maxBufferSize ?? 2e3;
+    const keepAlive = new http__namespace.Agent({ keepAlive: true });
+    const keepAliveHttps = new https__namespace.Agent({ keepAlive: true });
+    this.client = axios__default.default.create({
+      baseURL: opts.url,
+      timeout: opts.timeoutMs ?? 5e3,
+      httpAgent: keepAlive,
+      httpsAgent: keepAliveHttps,
+      headers: {
+        "Content-Type": "application/json",
+        ...opts.authToken ? { Authorization: `Bearer ${opts.authToken}` } : {},
+        ...opts.headers
+      }
+    });
+    this.cb = new circuitBreaker.CircuitBreaker({
+      ...TRANSPORT_CB_DEFAULTS,
+      ...opts.circuitBreaker,
+      name: "WinstonHttpTransport",
+      isFailure: () => true
+    });
+    this.flushTimer = setInterval(
+      () => {
+        void this.flush();
+      },
+      opts.flushIntervalMs ?? 5e3
+    );
+    this.flushTimer.unref?.();
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  log(info, callback) {
+    setImmediate(() => this.emit("logged", info));
+    if (this.buffer.length < this.maxBufferSize) {
+      this.buffer.push(info);
+    }
+    if (this.buffer.length >= this.batchSize) {
+      void this.flush();
+    }
+    callback();
+  }
+  /** Flush remaining buffer on graceful shutdown. */
+  async close() {
+    clearInterval(this.flushTimer);
+    await this.flush();
+  }
+  async flush() {
+    if (this.buffer.length === 0) return;
+    const batch = this.buffer.splice(0, this.batchSize);
+    try {
+      await this.cb.execute(() => this.client.post("", batch));
+    } catch (err) {
+      const room = this.maxBufferSize - this.buffer.length;
+      if (room > 0) this.buffer.unshift(...batch.slice(0, room));
+      if (!(err instanceof circuitBreaker.CircuitBreakerOpenError)) {
+        console.error(`[WinstonHttpTransport] flush failed \u2014 re-queued ${batch.length} entries`, err);
+      }
+    }
+  }
+};
+
+// src/logger/logger.service.ts
+exports.LoggerService = class LoggerService {
+  constructor(opts, correlationSvc) {
+    this.opts = opts;
+    this.correlationSvc = correlationSvc;
+    const transports2 = [
+      new winston__namespace.transports.Console({
+        format: winston__namespace.format.combine(
+          winston__namespace.format.timestamp(),
+          winston__namespace.format.colorize(),
+          winston__namespace.format.printf(({ level, message, timestamp, ...meta }) => {
+            const extra = Object.keys(meta).length ? ` ${JSON.stringify(meta)}` : "";
+            return `${timestamp} [${level}] ${message}${extra}`;
+          })
+        )
+      })
+    ];
+    if (opts.http) {
+      transports2.push(
+        new WinstonHttpTransport({
+          ...opts.http,
+          format: winston__namespace.format.json()
+        })
+      );
+    }
+    this.winston = winston__namespace.createLogger({
+      level: opts.logLevel ?? "info",
+      transports: transports2,
+      format: winston__namespace.format.json()
+    });
+  }
+  opts;
+  correlationSvc;
+  winston;
+  log(message, context) {
+    this.winston.info(message, this.buildMeta(context));
+  }
+  error(message, trace, context) {
+    this.winston.error(message, { ...this.buildMeta(context), trace });
+  }
+  warn(message, context) {
+    this.winston.warn(message, this.buildMeta(context));
+  }
+  debug(message, context) {
+    this.winston.debug(message, this.buildMeta(context));
+  }
+  verbose(message, context) {
+    this.winston.verbose(message, this.buildMeta(context));
+  }
+  /** Log with additional arbitrary metadata. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  logWithMeta(level, message, meta) {
+    this.winston.log(level, message, { ...this.buildMeta(), ...meta });
+  }
+  buildMeta(context) {
+    const base = {
+      service: this.opts.serviceName,
+      environment: this.opts.environment ?? "production",
+      correlationId: this.correlationSvc?.get()
+    };
+    if (context) base.context = context;
+    return base;
+  }
+};
+exports.LoggerService = __decorateClass([
+  common.Injectable(),
+  __decorateParam(0, common.Inject(OBSERVABILITY_OPTIONS)),
+  __decorateParam(1, common.Optional())
+], exports.LoggerService);
+var TRANSPORT_CB_DEFAULTS2 = {
+  failureThreshold: 60,
+  slowCallThreshold: 100,
+  slowCallDurationMs: 6e4,
+  minimumCalls: 3,
+  slidingWindowSize: 5,
+  halfOpenMaxCalls: 1,
+  openTimeoutMs: 3e4
+};
+exports.MetricsService = class MetricsService {
+  constructor(opts, correlationSvc) {
+    this.opts = opts;
+    this.correlationSvc = correlationSvc;
+    if (!opts.metrics) return;
+    const m = opts.metrics;
+    this.maxBufferSize = m.maxBufferSize ?? 5e3;
+    const keepAlive = new http__namespace.Agent({ keepAlive: true });
+    const keepAliveHttps = new https__namespace.Agent({ keepAlive: true });
+    this.client = axios__default.default.create({
+      baseURL: m.url,
+      timeout: m.timeoutMs ?? 5e3,
+      httpAgent: keepAlive,
+      httpsAgent: keepAliveHttps,
+      headers: {
+        "Content-Type": "application/json",
+        ...m.authToken ? { Authorization: `Bearer ${m.authToken}` } : {},
+        ...m.headers
+      }
+    });
+    this.cb = new circuitBreaker.CircuitBreaker({
+      ...TRANSPORT_CB_DEFAULTS2,
+      ...m.circuitBreaker,
+      name: "MetricsService",
+      isFailure: () => true,
+      onStateChange: (from, to, metrics) => {
+        if (to === circuitBreaker.CircuitBreakerState.OPEN) {
+          this.logger.warn(
+            `[MetricsService] circuit breaker OPEN \u2014 pausing metric sends for ${(m.circuitBreaker?.openTimeoutMs ?? TRANSPORT_CB_DEFAULTS2.openTimeoutMs) / 1e3}s`,
+            metrics
+          );
+        } else if (to === circuitBreaker.CircuitBreakerState.CLOSED && from !== circuitBreaker.CircuitBreakerState.HALF_OPEN) {
+          this.logger.log(`[MetricsService] circuit breaker CLOSED \u2014 recovered`);
+        }
+        m.circuitBreaker?.onStateChange?.(from, to, metrics);
+      }
+    });
+    this.flushTimer = setInterval(
+      () => {
+        void this.flush();
+      },
+      m.flushIntervalMs ?? 1e4
+    );
+    this.flushTimer.unref?.();
+  }
+  opts;
+  correlationSvc;
+  client = null;
+  cb = null;
+  logger = new common.Logger(exports.MetricsService.name);
+  buffer = [];
+  maxBufferSize = 5e3;
+  flushTimer = null;
+  /**
+   * Enqueue a metric event. Fire-and-forget; batched and sent on the next
+   * flush interval or when the buffer reaches `maxBufferSize`.
+   */
+  record(name, value, options) {
+    if (!this.client) return;
+    if (this.buffer.length >= this.maxBufferSize) {
+      this.logger.warn("[MetricsService] buffer full \u2014 dropping metric");
+      return;
+    }
+    this.buffer.push({
+      name,
+      value,
+      unit: options?.unit,
+      tags: options?.tags,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      serviceName: this.opts.serviceName,
+      environment: this.opts.environment ?? "production",
+      correlationId: this.correlationSvc?.getOrUndefined()
+    });
+  }
+  /** Flush on graceful shutdown. */
+  async onModuleDestroy() {
+    if (this.flushTimer) clearInterval(this.flushTimer);
+    await this.flush();
+  }
+  async flush() {
+    if (!this.client || this.buffer.length === 0) return;
+    const batch = this.buffer.splice(0, 500);
+    try {
+      await this.cb.execute(() => this.client.post("", batch));
+    } catch (err) {
+      const room = this.maxBufferSize - this.buffer.length;
+      if (room > 0) this.buffer.unshift(...batch.slice(0, room));
+      if (!(err instanceof circuitBreaker.CircuitBreakerOpenError)) {
+        this.logger.warn(
+          `[MetricsService] flush failed \u2014 re-queueing ${batch.length} events`,
+          err
+        );
+      }
+    }
+  }
+};
+exports.MetricsService = __decorateClass([
+  common.Injectable(),
+  __decorateParam(0, common.Inject(OBSERVABILITY_OPTIONS)),
+  __decorateParam(1, common.Optional())
+], exports.MetricsService);
+var CORRELATION_HEADER = "x-correlation-id";
+exports.CorrelationInterceptor = class CorrelationInterceptor {
+  constructor(correlationSvc) {
+    this.correlationSvc = correlationSvc;
+  }
+  correlationSvc;
+  intercept(ctx, next) {
+    const req = ctx.switchToHttp().getRequest();
+    const res = ctx.switchToHttp().getResponse();
+    const incomingId = req.headers?.[CORRELATION_HEADER];
+    const correlationId = typeof incomingId === "string" && incomingId ? incomingId : crypto.randomUUID();
+    res.setHeader(CORRELATION_HEADER, correlationId);
+    return new rxjs.Observable((subscriber) => {
+      this.correlationSvc.run(correlationId, () => {
+        next.handle().pipe(
+          operators.tap({ error: () => {
+          } })
+        ).subscribe(subscriber);
+      });
+    });
+  }
+};
+exports.CorrelationInterceptor = __decorateClass([
+  common.Injectable(),
+  __decorateParam(0, common.Inject(exports.CorrelationIdService))
+], exports.CorrelationInterceptor);
+exports.PerformanceInterceptor = class PerformanceInterceptor {
+  constructor(logger, metrics, correlationSvc) {
+    this.logger = logger;
+    this.metrics = metrics;
+    this.correlationSvc = correlationSvc;
+  }
+  logger;
+  metrics;
+  correlationSvc;
+  intercept(ctx, next) {
+    const start = Date.now();
+    const req = ctx.switchToHttp().getRequest();
+    const method = req.method ?? "UNKNOWN";
+    const path = req.url ?? "UNKNOWN";
+    return next.handle().pipe(
+      operators.tap({
+        next: () => {
+          const durationMs = Date.now() - start;
+          this.record(method, path, "success", durationMs);
+        },
+        error: () => {
+          const durationMs = Date.now() - start;
+          this.record(method, path, "error", durationMs);
+        }
+      })
+    );
+  }
+  record(method, path, outcome, durationMs) {
+    const correlationId = this.correlationSvc?.getOrUndefined();
+    const span = getActiveSpan();
+    span?.setAttribute("http.method", method);
+    span?.setAttribute("http.target", path);
+    span?.setAttribute("http.duration_ms", durationMs);
+    this.logger.logWithMeta("info", `${method} ${path} [${outcome}] ${durationMs}ms`, {
+      method,
+      path,
+      outcome,
+      durationMs,
+      correlationId
+    });
+    this.metrics?.record("http.request.duration", durationMs, {
+      unit: "ms",
+      tags: { method, path, outcome }
+    });
+  }
+};
+exports.PerformanceInterceptor = __decorateClass([
+  common.Injectable(),
+  __decorateParam(0, common.Inject(exports.LoggerService)),
+  __decorateParam(1, common.Optional()),
+  __decorateParam(1, common.Inject(exports.MetricsService)),
+  __decorateParam(2, common.Optional()),
+  __decorateParam(2, common.Inject(exports.CorrelationIdService))
+], exports.PerformanceInterceptor);
+exports.AllExceptionsFilter = class AllExceptionsFilter {
+  constructor(logger, correlationSvc) {
+    this.logger = logger;
+    this.correlationSvc = correlationSvc;
+  }
+  logger;
+  correlationSvc;
+  mappers = [];
+  /**
+   * Register a custom error mapper.
+   * Mappers are tried in order; the first non-null result wins.
+   * Return `null` to fall through to the next mapper.
+   */
+  addMapper(mapper) {
+    this.mappers.push(mapper);
+    return this;
+  }
+  catch(exception, host) {
+    const ctx = host.switchToHttp();
+    const res = ctx.getResponse();
+    const mapped = this.resolveError(exception);
+    const correlationId = this.correlationSvc?.getOrUndefined();
+    const span = getActiveSpan();
+    span?.recordException(exception instanceof Error ? exception : new Error(String(exception)));
+    this.logger.error(
+      mapped.message,
+      exception instanceof Error ? exception.stack : void 0,
+      exports.AllExceptionsFilter.name
+    );
+    res.status(mapped.statusCode).json({
+      ok: false,
+      statusCode: mapped.statusCode,
+      message: mapped.message,
+      code: mapped.code,
+      correlationId,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  resolveError(exception) {
+    for (const mapper of this.mappers) {
+      const result = mapper(exception);
+      if (result !== null) return result;
+    }
+    if (exception instanceof common.HttpException) {
+      const body = exception.getResponse();
+      const message = typeof body === "string" ? body : body.message ?? exception.message;
+      return { statusCode: exception.getStatus(), message };
+    }
+    return {
+      statusCode: common.HttpStatus.INTERNAL_SERVER_ERROR,
+      message: "Internal server error"
+    };
+  }
+};
+exports.AllExceptionsFilter = __decorateClass([
+  common.Catch(),
+  __decorateParam(0, common.Inject(exports.LoggerService)),
+  __decorateParam(1, common.Optional()),
+  __decorateParam(1, common.Inject(exports.CorrelationIdService))
+], exports.AllExceptionsFilter);
+
+// src/observability.module.ts
+exports.ObservabilityModule = class ObservabilityModule {
+  static forRoot(options) {
+    const optionsProvider = {
+      provide: OBSERVABILITY_OPTIONS,
+      useValue: options
+    };
+    const providers = [
+      optionsProvider,
+      exports.CorrelationIdService,
+      exports.LoggerService,
+      exports.MetricsService,
+      exports.CorrelationInterceptor,
+      exports.PerformanceInterceptor,
+      exports.AllExceptionsFilter
+    ];
+    return {
+      module: exports.ObservabilityModule,
+      global: true,
+      providers,
+      exports: [
+        exports.CorrelationIdService,
+        exports.LoggerService,
+        exports.MetricsService,
+        exports.CorrelationInterceptor,
+        exports.PerformanceInterceptor,
+        exports.AllExceptionsFilter
+      ]
+    };
+  }
+};
+exports.ObservabilityModule = __decorateClass([
+  common.Module({})
+], exports.ObservabilityModule);
+
+// src/decorators/track-performance.decorator.ts
+function TrackPerformance(options = {}) {
+  return function(target, propertyKey, descriptor) {
+    const original = descriptor.value;
+    const operationName = options.operation ?? `${target.constructor.name}.${String(propertyKey)}`;
+    descriptor.value = async function(...args) {
+      const tracer = getTracer("@backendkit-labs/observability");
+      const span = tracer.startSpan(operationName);
+      if (options.attributes) {
+        span.setAttributes(options.attributes);
+      }
+      try {
+        const result = await runInOtelContext(span, () => original.apply(this, args));
+        span.setStatus({ code: 1 });
+        return result;
+      } catch (err) {
+        span.recordException(err instanceof Error ? err : new Error(String(err)));
+        span.setStatus({ code: 2, message: String(err) });
+        throw err;
+      } finally {
+        span.end();
+      }
+    };
+    return descriptor;
+  };
+}
+
+exports.OBSERVABILITY_OPTIONS = OBSERVABILITY_OPTIONS;
+exports.TrackPerformance = TrackPerformance;
+exports.WinstonHttpTransport = WinstonHttpTransport;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map