@shuttle-labs/node-observability 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { ObservabilityModule } from './nestjs';
+export { getMetricsMeter } from './metrics';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMetricsMeter = exports.ObservabilityModule = void 0;
+var nestjs_1 = require("./nestjs");
+Object.defineProperty(exports, "ObservabilityModule", { enumerable: true, get: function () { return nestjs_1.ObservabilityModule; } });
+var metrics_1 = require("./metrics");
+Object.defineProperty(exports, "getMetricsMeter", { enumerable: true, get: function () { return metrics_1.getMetricsMeter; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,mCAA+C;AAAtC,6GAAA,mBAAmB,OAAA;AAC5B,qCAA4C;AAAnC,0GAAA,eAAe,OAAA"}

package/dist/metrics.d.ts

@@ -0,0 +1,10 @@
+import { type Meter } from '@opentelemetry/api';
+/**
+ * Returns an OTel Meter. Call after register() has initialized the SDK.
+ * Usage:
+ *   const meter = getMetricsMeter();
+ *   const counter = meter.createCounter('my_counter');
+ *   counter.add(1, { label: 'value' });
+ */
+export declare const getMetricsMeter: (name?: string, version?: string) => Meter;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEzD;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,EAAE,UAAU,MAAM,KAAG,KAIjE,CAAC"}

package/dist/metrics.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMetricsMeter = void 0;
+const api_1 = require("@opentelemetry/api");
+/**
+ * Returns an OTel Meter. Call after register() has initialized the SDK.
+ * Usage:
+ *   const meter = getMetricsMeter();
+ *   const counter = meter.createCounter('my_counter');
+ *   counter.add(1, { label: 'value' });
+ */
+const getMetricsMeter = (name, version) => {
+    const svcName = name ?? process.env.OTEL_SERVICE_NAME ?? 'unknown-service';
+    const svcVersion = version ?? process.env.OTEL_SERVICE_VERSION ?? '1.0.0';
+    return api_1.metrics.getMeter(svcName, svcVersion);
+};
+exports.getMetricsMeter = getMetricsMeter;
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":";;;AAAA,4CAAyD;AAEzD;;;;;;GAMG;AACI,MAAM,eAAe,GAAG,CAAC,IAAa,EAAE,OAAgB,EAAS,EAAE;IACxE,MAAM,OAAO,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,iBAAiB,CAAC;IAC3E,MAAM,UAAU,GAAG,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,OAAO,CAAC;IAC1E,OAAO,aAAO,CAAC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;AAC/C,CAAC,CAAC;AAJW,QAAA,eAAe,mBAI1B"}

package/dist/nestjs.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Drop-in replacement for LoggerModule in NestJS apps.
+ * - Development: pino-pretty (colorized, readable)
+ * - Production:  pino-opentelemetry-transport → OTLP → SigNoz
+ *                (reads OTEL_SERVICE_NAME + OTEL_EXPORTER_OTLP_ENDPOINT from env)
+ */
+export declare class ObservabilityModule {
+}
+//# sourceMappingURL=nestjs.d.ts.map

package/dist/nestjs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nestjs.d.ts","sourceRoot":"","sources":["../src/nestjs.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,qBAYa,mBAAmB;CAAG"}

package/dist/nestjs.js

@@ -0,0 +1,75 @@
+"use strict";
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObservabilityModule = void 0;
+const common_1 = require("@nestjs/common");
+const nestjs_pino_1 = require("nestjs-pino");
+/**
+ * Drop-in replacement for LoggerModule in NestJS apps.
+ * - Development: pino-pretty (colorized, readable)
+ * - Production:  pino-opentelemetry-transport → OTLP → SigNoz
+ *                (reads OTEL_SERVICE_NAME + OTEL_EXPORTER_OTLP_ENDPOINT from env)
+ */
+let ObservabilityModule = (() => {
+    let _classDecorators = [(0, common_1.Module)({
+            imports: [
+                nestjs_pino_1.LoggerModule.forRoot({
+                    pinoHttp: {
+                        level: process.env.NODE_ENV === 'production' ? 'info' : 'debug',
+                        transport: process.env.NODE_ENV !== 'production'
+                            ? { target: 'pino-pretty', options: { colorize: true, singleLine: true } }
+                            : { target: 'pino-opentelemetry-transport' },
+                    },
+                }),
+            ],
+        })];
+    let _classDescriptor;
+    let _classExtraInitializers = [];
+    let _classThis;
+    var ObservabilityModule = class {
+        static { _classThis = this; }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+            ObservabilityModule = _classThis = _classDescriptor.value;
+            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+            __runInitializers(_classThis, _classExtraInitializers);
+        }
+    };
+    return ObservabilityModule = _classThis;
+})();
+exports.ObservabilityModule = ObservabilityModule;
+//# sourceMappingURL=nestjs.js.map

package/dist/nestjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nestjs.js","sourceRoot":"","sources":["../src/nestjs.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,2CAAwC;AACxC,6CAA2C;AAE3C;;;;;GAKG;IAaU,mBAAmB;4BAZ/B,IAAA,eAAM,EAAC;YACN,OAAO,EAAE;gBACP,0BAAY,CAAC,OAAO,CAAC;oBACnB,QAAQ,EAAE;wBACR,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO;wBAC/D,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;4BAC9C,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE;4BAC1E,CAAC,CAAC,EAAE,MAAM,EAAE,8BAA8B,EAAE;qBAC/C;iBACF,CAAC;aACH;SACF,CAAC;;;;;;;;YACF,6KAAmC;;;YAAtB,uDAAmB;;;;;AAAnB,kDAAmB"}

package/dist/register.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=register.d.ts.map

package/dist/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":""}

package/dist/register.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const sdk_node_1 = require("@opentelemetry/sdk-node");
+const auto_instrumentations_node_1 = require("@opentelemetry/auto-instrumentations-node");
+const exporter_metrics_otlp_http_1 = require("@opentelemetry/exporter-metrics-otlp-http");
+const sdk_metrics_1 = require("@opentelemetry/sdk-metrics");
+// Guard against double-initialization (e.g. hot reload, test environments)
+const g = global;
+if (!g.__otelSdkInitialized) {
+    g.__otelSdkInitialized = true;
+    const exportIntervalMillis = Number(process.env.OTEL_METRIC_EXPORT_INTERVAL ?? 15000);
+    const sdk = new sdk_node_1.NodeSDK({
+        // Resource (service.name, deployment.environment) is read automatically
+        // from OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES env vars
+        // Traces — exported via OTEL_EXPORTER_OTLP_ENDPOINT (set by deploy-ecs action)
+        // Metrics
+        metricReader: new sdk_metrics_1.PeriodicExportingMetricReader({
+            exporter: new exporter_metrics_otlp_http_1.OTLPMetricExporter(),
+            exportIntervalMillis: Number.isFinite(exportIntervalMillis) ? exportIntervalMillis : 15000,
+        }),
+        // Auto-instrumentation: HTTP, NestJS, Express, TypeORM, Kafka, Redis, pg, etc.
+        instrumentations: [
+            (0, auto_instrumentations_node_1.getNodeAutoInstrumentations)({
+                // fs instrumentation is very noisy — disable it
+                '@opentelemetry/instrumentation-fs': { enabled: false },
+            }),
+        ],
+    });
+    sdk.start();
+    process.on('SIGTERM', () => {
+        sdk.shutdown().catch(() => { });
+    });
+}
+//# sourceMappingURL=register.js.map

package/dist/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":";;AAAA,sDAAkD;AAClD,0FAAwF;AACxF,0FAA+E;AAC/E,4DAA2E;AAE3E,2EAA2E;AAC3E,MAAM,CAAC,GAAG,MAA4D,CAAC;AACvE,IAAI,CAAC,CAAC,CAAC,oBAAoB,EAAE,CAAC;IAC5B,CAAC,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAE9B,MAAM,oBAAoB,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,2BAA2B,IAAI,KAAK,CAAC,CAAC;IAEtF,MAAM,GAAG,GAAG,IAAI,kBAAO,CAAC;QACtB,wEAAwE;QACxE,+DAA+D;QAE/D,+EAA+E;QAC/E,UAAU;QACV,YAAY,EAAE,IAAI,2CAA6B,CAAC;YAC9C,QAAQ,EAAE,IAAI,+CAAkB,EAAE;YAClC,oBAAoB,EAAE,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,KAAK;SAC3F,CAAC;QAEF,+EAA+E;QAC/E,gBAAgB,EAAE;YAChB,IAAA,wDAA2B,EAAC;gBAC1B,gDAAgD;gBAChD,mCAAmC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE;aACxD,CAAC;SACH;KACF,CAAC,CAAC;IAEH,GAAG,CAAC,KAAK,EAAE,CAAC;IAEZ,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;QACzB,GAAG,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@shuttle-labs/node-observability",
+  "version": "1.0.0",
+  "description": "Shared OTel observability for Node.js services — traces, logs, metrics",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./register": "./dist/register.js",
+    "./nestjs": "./dist/nestjs.js"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.71.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.205.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.213.0",
+    "@opentelemetry/resources": "^2.1.0",
+    "@opentelemetry/sdk-metrics": "^2.1.0",
+    "@opentelemetry/sdk-node": "^0.213.0",
+    "@opentelemetry/semantic-conventions": "^1.37.0",
+    "pino": "^9.0.0",
+    "pino-opentelemetry-transport": "^3.0.0"
+  },
+  "peerDependencies": {
+    "nestjs-pino": "^4.0.0",
+    "pino-http": "^10.0.0"
+  },
+  "peerDependenciesMeta": {
+    "nestjs-pino": {
+      "optional": true
+    },
+    "pino-http": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { ObservabilityModule } from './nestjs';
+export { getMetricsMeter } from './metrics';

package/src/metrics.ts

@@ -0,0 +1,14 @@
+import { metrics, type Meter } from '@opentelemetry/api';
+
+/**
+ * Returns an OTel Meter. Call after register() has initialized the SDK.
+ * Usage:
+ *   const meter = getMetricsMeter();
+ *   const counter = meter.createCounter('my_counter');
+ *   counter.add(1, { label: 'value' });
+ */
+export const getMetricsMeter = (name?: string, version?: string): Meter => {
+  const svcName = name ?? process.env.OTEL_SERVICE_NAME ?? 'unknown-service';
+  const svcVersion = version ?? process.env.OTEL_SERVICE_VERSION ?? '1.0.0';
+  return metrics.getMeter(svcName, svcVersion);
+};

package/src/nestjs.ts

@@ -0,0 +1,22 @@
+import { Module } from '@nestjs/common';
+import { LoggerModule } from 'nestjs-pino';
+
+/**
+ * Drop-in replacement for LoggerModule in NestJS apps.
+ * - Development: pino-pretty (colorized, readable)
+ * - Production:  pino-opentelemetry-transport → OTLP → SigNoz
+ *                (reads OTEL_SERVICE_NAME + OTEL_EXPORTER_OTLP_ENDPOINT from env)
+ */
+@Module({
+  imports: [
+    LoggerModule.forRoot({
+      pinoHttp: {
+        level: process.env.NODE_ENV === 'production' ? 'info' : 'debug',
+        transport: process.env.NODE_ENV !== 'production'
+          ? { target: 'pino-pretty', options: { colorize: true, singleLine: true } }
+          : { target: 'pino-opentelemetry-transport' },
+      },
+    }),
+  ],
+})
+export class ObservabilityModule {}

package/src/register.ts

@@ -0,0 +1,38 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
+import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
+
+// Guard against double-initialization (e.g. hot reload, test environments)
+const g = global as typeof global & { __otelSdkInitialized?: boolean };
+if (!g.__otelSdkInitialized) {
+  g.__otelSdkInitialized = true;
+
+  const exportIntervalMillis = Number(process.env.OTEL_METRIC_EXPORT_INTERVAL ?? 15000);
+
+  const sdk = new NodeSDK({
+    // Resource (service.name, deployment.environment) is read automatically
+    // from OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES env vars
+
+    // Traces — exported via OTEL_EXPORTER_OTLP_ENDPOINT (set by deploy-ecs action)
+    // Metrics
+    metricReader: new PeriodicExportingMetricReader({
+      exporter: new OTLPMetricExporter(),
+      exportIntervalMillis: Number.isFinite(exportIntervalMillis) ? exportIntervalMillis : 15000,
+    }),
+
+    // Auto-instrumentation: HTTP, NestJS, Express, TypeORM, Kafka, Redis, pg, etc.
+    instrumentations: [
+      getNodeAutoInstrumentations({
+        // fs instrumentation is very noisy — disable it
+        '@opentelemetry/instrumentation-fs': { enabled: false },
+      }),
+    ],
+  });
+
+  sdk.start();
+
+  process.on('SIGTERM', () => {
+    sdk.shutdown().catch(() => {});
+  });
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}