@backendkit-labs/observability 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,184 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and the Work's derivative works.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as
+      "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and subsequently
+      incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any
+      Contribution embodied within the Work constitutes direct or contributory
+      patent infringement, then any patent licenses granted to You under
+      this License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or in addition to the
+          NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, and
+      distribute Your modifications, or for such Derivative Works as a
+      whole, subject to the terms and conditions of this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2024-2026 Mairon José Cuello Martínez
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/README.md

@@ -1,5 +1,7 @@
 # @backendkit-labs/observability
 
+[![Docs](https://img.shields.io/badge/docs-backendkitlabs.dev-4f7eff?style=flat-square)](https://backendkitlabs.dev/docs/observability/)
+
 Structured logging, distributed tracing correlation, metrics shipping, performance interceptors, and exception handling for **NestJS** — with optional OpenTelemetry integration.
 
 ## Features
@@ -364,4 +366,4 @@ The same `circuitBreaker` option is available on the `http` log transport.
 
 ## License
 
-MIT
+Apache-2.0

package/dist/index.cjs

@@ -2,7 +2,7 @@
 
 var common = require('@nestjs/common');
 var async_hooks = require('async_hooks');
-var crypto = require('crypto');
+var module$1 = require('module');
 var winston = require('winston');
 var TransportStream = require('winston-transport');
 var axios = require('axios');
@@ -10,8 +10,10 @@ var http = require('http');
 var https = require('https');
 var circuitBreaker = require('@backendkit-labs/circuit-breaker');
 var rxjs = require('rxjs');
+var crypto = require('crypto');
 var operators = require('rxjs/operators');
 
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 function _interopNamespace(e) {
@@ -39,12 +41,6 @@ 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--)
@@ -53,11 +49,10 @@ var __decorateClass = (decorators, target, key, kind) => {
   return result;
 };
 var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
-
-// src/internal/otel.ts
+var _require = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
 var otel = null;
 try {
-  otel = __require("@opentelemetry/api");
+  otel = _require("@opentelemetry/api");
 } catch {
 }
 var getTracer = (name) => otel?.trace?.getTracer(name) ?? noopTracer;
@@ -95,9 +90,9 @@ exports.CorrelationIdService = class CorrelationIdService {
   run(correlationId, fn) {
     return storage.run(correlationId, fn);
   }
-  /** Current correlation ID, or a fresh UUID when called outside a context. */
+  /** Current correlation ID, or 'no-context' when called outside a context. */
   get() {
-    return storage.getStore() ?? crypto.randomUUID();
+    return storage.getStore() ?? "no-context";
   }
   /**
    * Current correlation ID, or `undefined` when called outside a context.
@@ -134,12 +129,18 @@ var TRANSPORT_CB_DEFAULTS = {
   halfOpenMaxCalls: 1,
   openTimeoutMs: 3e4
 };
-var WinstonHttpTransport = class extends TransportStream__default.default {
+var WinstonHttpTransport = class _WinstonHttpTransport extends TransportStream__default.default {
   client;
   cb;
   buffer = [];
   batchSize;
   maxBufferSize;
+  maxEntryAgeMs = 3e5;
+  // 5 min
+  fallbackLogger = new common.Logger(_WinstonHttpTransport.name);
+  retryCounts = /* @__PURE__ */ new WeakMap();
+  entryTimes = /* @__PURE__ */ new WeakMap();
+  maxRetries = 5;
   flushTimer;
   constructor(opts) {
     super(opts);
@@ -158,11 +159,23 @@ var WinstonHttpTransport = class extends TransportStream__default.default {
         ...opts.headers
       }
     });
+    this.client.interceptors.response.use(
+      (response) => response,
+      (error) => {
+        if (error.config?.headers?.Authorization) {
+          error.config.headers.Authorization = "Bearer ***REDACTED***";
+        }
+        return Promise.reject(error);
+      }
+    );
     this.cb = new circuitBreaker.CircuitBreaker({
       ...TRANSPORT_CB_DEFAULTS,
       ...opts.circuitBreaker,
       name: "WinstonHttpTransport",
-      isFailure: () => true
+      isFailure: (error) => {
+        const status = error.response?.status;
+        return status !== void 0 ? status >= 400 : true;
+      }
     });
     this.flushTimer = setInterval(
       () => {
@@ -174,9 +187,11 @@ var WinstonHttpTransport = class extends TransportStream__default.default {
   }
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   log(info, callback) {
-    setImmediate(() => this.emit("logged", info));
+    this.emit("logged", info);
     if (this.buffer.length < this.maxBufferSize) {
-      this.buffer.push(info);
+      const entry = { ...info };
+      this.entryTimes.set(entry, Date.now());
+      this.buffer.push(entry);
     }
     if (this.buffer.length >= this.batchSize) {
       void this.flush();
@@ -190,14 +205,24 @@ var WinstonHttpTransport = class extends TransportStream__default.default {
   }
   async flush() {
     if (this.buffer.length === 0) return;
+    const now = Date.now();
+    this.buffer = this.buffer.filter(
+      (e) => now - (this.entryTimes.get(e) ?? now) < this.maxEntryAgeMs
+    );
     const batch = this.buffer.splice(0, this.batchSize);
     try {
       await this.cb.execute(() => this.client.post("", batch));
     } catch (err) {
+      const retryable = batch.filter((entry) => {
+        const retries = this.retryCounts.get(entry) ?? 0;
+        if (retries >= this.maxRetries) return false;
+        this.retryCounts.set(entry, retries + 1);
+        return true;
+      });
       const room = this.maxBufferSize - this.buffer.length;
-      if (room > 0) this.buffer.unshift(...batch.slice(0, room));
+      if (room > 0) this.buffer.unshift(...retryable.slice(0, room));
       if (!(err instanceof circuitBreaker.CircuitBreakerOpenError)) {
-        console.error(`[WinstonHttpTransport] flush failed \u2014 re-queued ${batch.length} entries`, err);
+        this.fallbackLogger.warn(`flush failed \u2014 re-queued ${retryable.length}/${batch.length} entries`, err.message);
       }
     }
   }
@@ -253,9 +278,10 @@ exports.LoggerService = class LoggerService {
     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 });
+    const validLevels = ["error", "warn", "info", "debug", "verbose"];
+    const safeLevel = validLevels.includes(level) ? level : "info";
+    this.winston.log(safeLevel, message, { ...this.buildMeta(), ...meta });
   }
   buildMeta(context) {
     const base = {
@@ -305,7 +331,10 @@ exports.MetricsService = class MetricsService {
       ...TRANSPORT_CB_DEFAULTS2,
       ...m.circuitBreaker,
       name: "MetricsService",
-      isFailure: () => true,
+      isFailure: (error) => {
+        const status = error.response?.status;
+        return status !== void 0 ? status >= 400 : true;
+      },
       onStateChange: (from, to, metrics) => {
         if (to === circuitBreaker.CircuitBreakerState.OPEN) {
           this.logger.warn(
@@ -333,6 +362,10 @@ exports.MetricsService = class MetricsService {
   logger = new common.Logger(exports.MetricsService.name);
   buffer = [];
   maxBufferSize = 5e3;
+  maxEntryAgeMs = 3e5;
+  // 5 min
+  retryCounts = /* @__PURE__ */ new WeakMap();
+  maxRetries = 5;
   flushTimer = null;
   /**
    * Enqueue a metric event. Fire-and-forget; batched and sent on the next
@@ -358,20 +391,33 @@ exports.MetricsService = class MetricsService {
   /** Flush on graceful shutdown. */
   async onModuleDestroy() {
     if (this.flushTimer) clearInterval(this.flushTimer);
-    await this.flush();
+    try {
+      await this.flush();
+    } catch {
+    }
   }
   async flush() {
     if (!this.client || this.buffer.length === 0) return;
+    const now = Date.now();
+    this.buffer = this.buffer.filter(
+      (e) => now - new Date(e.timestamp).getTime() < this.maxEntryAgeMs
+    );
     const batch = this.buffer.splice(0, 500);
     try {
       await this.cb.execute(() => this.client.post("", batch));
     } catch (err) {
+      const retryable = batch.filter((entry) => {
+        const retries = this.retryCounts.get(entry) ?? 0;
+        if (retries >= this.maxRetries) return false;
+        this.retryCounts.set(entry, retries + 1);
+        return true;
+      });
       const room = this.maxBufferSize - this.buffer.length;
-      if (room > 0) this.buffer.unshift(...batch.slice(0, room));
+      if (room > 0) this.buffer.unshift(...retryable.slice(0, room));
       if (!(err instanceof circuitBreaker.CircuitBreakerOpenError)) {
         this.logger.warn(
-          `[MetricsService] flush failed \u2014 re-queueing ${batch.length} events`,
-          err
+          `[MetricsService] flush failed \u2014 re-queueing ${retryable.length}/${batch.length} events`,
+          err.message
         );
       }
     }
@@ -383,6 +429,13 @@ exports.MetricsService = __decorateClass([
   __decorateParam(1, common.Optional())
 ], exports.MetricsService);
 var CORRELATION_HEADER = "x-correlation-id";
+var CORRELATION_ID_REGEX = /^[a-zA-Z0-9\-_:]{1,64}$/;
+function sanitizeCorrelationId(raw) {
+  if (typeof raw !== "string") return null;
+  if (raw.length > 64) return null;
+  if (!CORRELATION_ID_REGEX.test(raw)) return null;
+  return raw;
+}
 exports.CorrelationInterceptor = class CorrelationInterceptor {
   constructor(correlationSvc) {
     this.correlationSvc = correlationSvc;
@@ -392,14 +445,11 @@ exports.CorrelationInterceptor = class CorrelationInterceptor {
     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();
+    const correlationId = sanitizeCorrelationId(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);
+        next.handle().subscribe(subscriber);
       });
     });
   }
@@ -507,7 +557,8 @@ exports.AllExceptionsFilter = class AllExceptionsFilter {
     }
     if (exception instanceof common.HttpException) {
       const body = exception.getResponse();
-      const message = typeof body === "string" ? body : body.message ?? exception.message;
+      const rawMessage = typeof body === "string" ? body : body.message ?? exception.message;
+      const message = Array.isArray(rawMessage) ? rawMessage.join("; ") : String(rawMessage ?? exception.message);
       return { statusCode: exception.getStatus(), message };
     }
     return {