@forinda/kickjs-otel 0.5.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Felix Orinda
+
+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/dist/index.d.ts

@@ -0,0 +1,66 @@
+import { AppAdapter, Container, AdapterMiddleware } from '@forinda/kickjs-core';
+
+interface OtelAdapterOptions {
+    /** Service name reported to the OTel backend (default: 'kickjs-app') */
+    serviceName?: string;
+    /** Service version (default: '0.0.0') */
+    serviceVersion?: string;
+    /** Enable HTTP request tracing (default: true) */
+    tracing?: boolean;
+    /** Enable request metrics — counter, histogram (default: true) */
+    metrics?: boolean;
+    /**
+     * Custom span attributes added to every request span.
+     * Receives the Express request object.
+     */
+    customAttributes?: (req: any) => Record<string, string | number | boolean>;
+    /**
+     * Routes to ignore from tracing (e.g., health checks).
+     * Supports exact match or prefix match with trailing *.
+     * @example ['/health', '/_debug/*', '/favicon.ico']
+     */
+    ignoreRoutes?: string[];
+}
+
+/**
+ * OpenTelemetry adapter for KickJS — automatic tracing and metrics.
+ *
+ * Creates spans for each HTTP request with route, method, status code,
+ * and duration. Optionally records request count and latency histograms.
+ *
+ * Works with any OTel-compatible backend: Jaeger, Grafana Tempo, Datadog,
+ * Honeycomb, etc. Configure exporters via the OTel SDK before bootstrapping.
+ *
+ * @example
+ * ```ts
+ * import { OtelAdapter } from '@forinda/kickjs-otel'
+ *
+ * // Set up OTel SDK (e.g., with Jaeger exporter) before bootstrap
+ * bootstrap({
+ *   modules,
+ *   adapters: [
+ *     new OtelAdapter({
+ *       serviceName: 'my-api',
+ *       serviceVersion: '1.0.0',
+ *       ignoreRoutes: ['/health', '/_debug/*'],
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+declare class OtelAdapter implements AppAdapter {
+    name: string;
+    private options;
+    private tracer;
+    private meter;
+    private requestCounter;
+    private requestDuration;
+    constructor(options?: OtelAdapterOptions);
+    beforeStart(_app: any, _container: Container): void;
+    middleware(): AdapterMiddleware[];
+    private onFinish;
+    private shouldIgnore;
+    shutdown(): Promise<void>;
+}
+
+export { OtelAdapter, type OtelAdapterOptions };

package/dist/index.js

@@ -0,0 +1,135 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+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');
+});
+
+// src/otel.adapter.ts
+import { Logger } from "@forinda/kickjs-core";
+var log = Logger.for("OtelAdapter");
+var OtelAdapter = class {
+  static {
+    __name(this, "OtelAdapter");
+  }
+  name = "OtelAdapter";
+  options;
+  tracer = null;
+  meter = null;
+  requestCounter = null;
+  requestDuration = null;
+  constructor(options = {}) {
+    this.options = {
+      serviceName: options.serviceName ?? "kickjs-app",
+      serviceVersion: options.serviceVersion ?? "0.0.0",
+      tracing: options.tracing ?? true,
+      metrics: options.metrics ?? true,
+      ...options
+    };
+  }
+  beforeStart(_app, _container) {
+    try {
+      const otelApi = __require("@opentelemetry/api");
+      if (this.options.tracing) {
+        this.tracer = otelApi.trace.getTracer(this.options.serviceName, this.options.serviceVersion);
+        log.info(`Tracing enabled for ${this.options.serviceName}`);
+      }
+      if (this.options.metrics) {
+        this.meter = otelApi.metrics.getMeter(this.options.serviceName, this.options.serviceVersion);
+        this.requestCounter = this.meter.createCounter("http.server.request.count", {
+          description: "Total number of HTTP requests"
+        });
+        this.requestDuration = this.meter.createHistogram("http.server.request.duration", {
+          description: "HTTP request duration in milliseconds",
+          unit: "ms"
+        });
+        log.info("Metrics enabled \u2014 http.server.request.count, http.server.request.duration");
+      }
+    } catch {
+      log.warn("OpenTelemetry API not found. Install @opentelemetry/api to enable tracing and metrics.");
+    }
+  }
+  middleware() {
+    return [
+      {
+        handler: /* @__PURE__ */ __name((req, res, next) => {
+          if (this.shouldIgnore(req.path)) {
+            return next();
+          }
+          const startTime = performance.now();
+          let span = null;
+          if (this.tracer) {
+            const otelApi = __require("@opentelemetry/api");
+            span = this.tracer.startSpan(`${req.method} ${req.route?.path ?? req.path}`, {
+              attributes: {
+                "http.method": req.method,
+                "http.url": req.originalUrl,
+                "http.target": req.path,
+                "http.user_agent": req.get("user-agent") ?? "",
+                "net.host.name": req.hostname,
+                ...this.options.customAttributes?.(req) ?? {}
+              }
+            });
+            const ctx = otelApi.trace.setSpan(otelApi.context.active(), span);
+            otelApi.context.with(ctx, () => {
+              this.onFinish(req, res, startTime, span);
+              next();
+            });
+            return;
+          }
+          this.onFinish(req, res, startTime, null);
+          next();
+        }, "handler"),
+        phase: "beforeGlobal"
+      }
+    ];
+  }
+  onFinish(req, res, startTime, span) {
+    res.on("finish", () => {
+      const duration = performance.now() - startTime;
+      const route = req.route?.path ?? req.path;
+      const attributes = {
+        "http.method": req.method,
+        "http.route": route,
+        "http.status_code": res.statusCode
+      };
+      if (span) {
+        span.setAttributes({
+          "http.status_code": res.statusCode,
+          "http.route": route
+        });
+        if (res.statusCode >= 400) {
+          span.setStatus({
+            code: 2,
+            message: `HTTP ${res.statusCode}`
+          });
+        }
+        span.end();
+      }
+      if (this.requestCounter) {
+        this.requestCounter.add(1, attributes);
+      }
+      if (this.requestDuration) {
+        this.requestDuration.record(duration, attributes);
+      }
+    });
+  }
+  shouldIgnore(path) {
+    if (!this.options.ignoreRoutes) return false;
+    return this.options.ignoreRoutes.some((pattern) => {
+      if (pattern.endsWith("*")) {
+        return path.startsWith(pattern.slice(0, -1));
+      }
+      return path === pattern;
+    });
+  }
+  async shutdown() {
+    log.info("OTel adapter shutdown");
+  }
+};
+export {
+  OtelAdapter
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/otel.adapter.ts"],"sourcesContent":["import {\n  Logger,\n  type AppAdapter,\n  type AdapterMiddleware,\n  type Container,\n} from '@forinda/kickjs-core'\nimport type { Request, Response, NextFunction } from 'express'\nimport type { OtelAdapterOptions } from './types'\n\nconst log = Logger.for('OtelAdapter')\n\n/**\n * OpenTelemetry adapter for KickJS — automatic tracing and metrics.\n *\n * Creates spans for each HTTP request with route, method, status code,\n * and duration. Optionally records request count and latency histograms.\n *\n * Works with any OTel-compatible backend: Jaeger, Grafana Tempo, Datadog,\n * Honeycomb, etc. Configure exporters via the OTel SDK before bootstrapping.\n *\n * @example\n * ```ts\n * import { OtelAdapter } from '@forinda/kickjs-otel'\n *\n * // Set up OTel SDK (e.g., with Jaeger exporter) before bootstrap\n * bootstrap({\n *   modules,\n *   adapters: [\n *     new OtelAdapter({\n *       serviceName: 'my-api',\n *       serviceVersion: '1.0.0',\n *       ignoreRoutes: ['/health', '/_debug/*'],\n *     }),\n *   ],\n * })\n * ```\n */\nexport class OtelAdapter implements AppAdapter {\n  name = 'OtelAdapter'\n  private options: Required<\n    Pick<OtelAdapterOptions, 'serviceName' | 'serviceVersion' | 'tracing' | 'metrics'>\n  > &\n    OtelAdapterOptions\n  private tracer: any = null\n  private meter: any = null\n  private requestCounter: any = null\n  private requestDuration: any = null\n\n  constructor(options: OtelAdapterOptions = {}) {\n    this.options = {\n      serviceName: options.serviceName ?? 'kickjs-app',\n      serviceVersion: options.serviceVersion ?? '0.0.0',\n      tracing: options.tracing ?? true,\n      metrics: options.metrics ?? true,\n      ...options,\n    }\n  }\n\n  beforeStart(_app: any, _container: Container): void {\n    try {\n      // Dynamically import OTel API — it's a peer dependency\n      const otelApi = require('@opentelemetry/api')\n\n      if (this.options.tracing) {\n        this.tracer = otelApi.trace.getTracer(this.options.serviceName, this.options.serviceVersion)\n        log.info(`Tracing enabled for ${this.options.serviceName}`)\n      }\n\n      if (this.options.metrics) {\n        this.meter = otelApi.metrics.getMeter(this.options.serviceName, this.options.serviceVersion)\n\n        this.requestCounter = this.meter.createCounter('http.server.request.count', {\n          description: 'Total number of HTTP requests',\n        })\n\n        this.requestDuration = this.meter.createHistogram('http.server.request.duration', {\n          description: 'HTTP request duration in milliseconds',\n          unit: 'ms',\n        })\n\n        log.info('Metrics enabled — http.server.request.count, http.server.request.duration')\n      }\n    } catch {\n      log.warn(\n        'OpenTelemetry API not found. Install @opentelemetry/api to enable tracing and metrics.',\n      )\n    }\n  }\n\n  middleware(): AdapterMiddleware[] {\n    return [\n      {\n        handler: (req: Request, res: Response, next: NextFunction) => {\n          // Skip ignored routes\n          if (this.shouldIgnore(req.path)) {\n            return next()\n          }\n\n          const startTime = performance.now()\n\n          // Start a span if tracing is enabled\n          let span: any = null\n          if (this.tracer) {\n            const otelApi = require('@opentelemetry/api')\n            span = this.tracer.startSpan(`${req.method} ${req.route?.path ?? req.path}`, {\n              attributes: {\n                'http.method': req.method,\n                'http.url': req.originalUrl,\n                'http.target': req.path,\n                'http.user_agent': req.get('user-agent') ?? '',\n                'net.host.name': req.hostname,\n                ...(this.options.customAttributes?.(req) ?? {}),\n              },\n            })\n\n            // Set span on context so downstream code can add attributes\n            const ctx = otelApi.trace.setSpan(otelApi.context.active(), span)\n            otelApi.context.with(ctx, () => {\n              this.onFinish(req, res, startTime, span)\n              next()\n            })\n            return\n          }\n\n          this.onFinish(req, res, startTime, null)\n          next()\n        },\n        phase: 'beforeGlobal',\n      },\n    ]\n  }\n\n  private onFinish(req: Request, res: Response, startTime: number, span: any): void {\n    res.on('finish', () => {\n      const duration = performance.now() - startTime\n      const route = (req as any).route?.path ?? req.path\n      const attributes = {\n        'http.method': req.method,\n        'http.route': route,\n        'http.status_code': res.statusCode,\n      }\n\n      // End span\n      if (span) {\n        span.setAttributes({\n          'http.status_code': res.statusCode,\n          'http.route': route,\n        })\n        if (res.statusCode >= 400) {\n          span.setStatus({ code: 2, message: `HTTP ${res.statusCode}` })\n        }\n        span.end()\n      }\n\n      // Record metrics\n      if (this.requestCounter) {\n        this.requestCounter.add(1, attributes)\n      }\n      if (this.requestDuration) {\n        this.requestDuration.record(duration, attributes)\n      }\n    })\n  }\n\n  private shouldIgnore(path: string): boolean {\n    if (!this.options.ignoreRoutes) return false\n    return this.options.ignoreRoutes.some((pattern) => {\n      if (pattern.endsWith('*')) {\n        return path.startsWith(pattern.slice(0, -1))\n      }\n      return path === pattern\n    })\n  }\n\n  async shutdown(): Promise<void> {\n    log.info('OTel adapter shutdown')\n  }\n}\n"],"mappings":"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","names":["Logger","log","Logger","for","OtelAdapter","name","options","tracer","meter","requestCounter","requestDuration","serviceName","serviceVersion","tracing","metrics","beforeStart","_app","_container","otelApi","require","trace","getTracer","info","getMeter","createCounter","description","createHistogram","unit","warn","middleware","handler","req","res","next","shouldIgnore","path","startTime","performance","now","span","startSpan","method","route","attributes","originalUrl","get","hostname","customAttributes","ctx","setSpan","context","active","with","onFinish","phase","on","duration","statusCode","setAttributes","setStatus","code","message","end","add","record","ignoreRoutes","some","pattern","endsWith","startsWith","slice","shutdown"]}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@forinda/kickjs-otel",
+  "version": "0.5.2",
+  "description": "OpenTelemetry adapter for KickJS — automatic tracing, metrics, and export to any OTel backend",
+  "keywords": [
+    "kickjs",
+    "nodejs",
+    "typescript",
+    "opentelemetry",
+    "otel",
+    "tracing",
+    "metrics",
+    "observability",
+    "jaeger",
+    "grafana",
+    "datadog",
+    "backend",
+    "framework",
+    "@forinda/kickjs-core",
+    "@forinda/kickjs-http"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "reflect-metadata": "^0.2.2",
+    "@forinda/kickjs-core": "0.6.0",
+    "@forinda/kickjs-http": "0.6.0"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": ">=1.4.0",
+    "@opentelemetry/sdk-node": ">=0.50.0",
+    "@opentelemetry/sdk-trace-base": ">=1.20.0",
+    "@opentelemetry/sdk-metrics": ">=1.20.0",
+    "@opentelemetry/semantic-conventions": ">=1.20.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/sdk-node": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-base": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-metrics": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-trace-base": "^1.30.1",
+    "@opentelemetry/sdk-metrics": "^1.30.1",
+    "@opentelemetry/semantic-conventions": "^1.28.0",
+    "@types/node": "^24.5.2",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Felix Orinda",
+  "engines": {
+    "node": ">=20.0"
+  },
+  "homepage": "https://forinda.github.io/kick-js/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/forinda/kick-js.git",
+    "directory": "packages/otel"
+  },
+  "bugs": {
+    "url": "https://github.com/forinda/kick-js/issues"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo",
+    "lint": "tsc --noEmit"
+  }
+}