@payloops/observability 0.0.1

package/.env.example

@@ -0,0 +1,4 @@
+# OpenTelemetry
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+OTEL_SERVICE_NAME=loop-service
+NODE_ENV=development

package/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+
+      - name: Update npm to latest
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Type check
+        run: pnpm typecheck
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Build
+        run: pnpm build

package/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Update npm to latest
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build
+        run: pnpm build
+
+      - name: Publish to npm with provenance
+        run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,152 @@
+# @payloops/observability
+
+Shared observability package for PayLoops services. Provides OpenTelemetry tracing, structured logging, correlation context, and metrics.
+
+## Installation
+
+```bash
+pnpm add @payloops/observability
+```
+
+## Features
+
+- **OpenTelemetry** - Automatic tracing and metrics export
+- **Structured Logging** - Pino logger with trace context
+- **Correlation Context** - AsyncLocalStorage for request tracking
+- **Metrics** - Pre-defined counters and histograms for payments, webhooks, HTTP, and workflows
+
+## Usage
+
+### Initialize Telemetry
+
+Initialize OpenTelemetry **before any other imports** in your entry point:
+
+```typescript
+import { initTelemetry } from '@payloops/observability';
+
+// Simple initialization
+initTelemetry('my-service', '1.0.0');
+
+// Or with full config
+initTelemetry({
+  serviceName: 'my-service',
+  serviceVersion: '1.0.0',
+  otlpEndpoint: 'http://localhost:4318',
+  environment: 'production',
+  enabledInstrumentations: {
+    http: true,
+    pg: true,
+    fs: false
+  }
+});
+```
+
+### Logging
+
+```typescript
+import { logger, createRequestLogger } from '@payloops/observability';
+
+// Basic logging (automatically includes trace context)
+logger.info({ orderId: '123' }, 'Processing order');
+
+// Create a request-scoped logger
+const reqLogger = createRequestLogger('req-123', 'POST', '/orders');
+reqLogger.info('Request started');
+```
+
+### Correlation Context
+
+Track requests across async boundaries:
+
+```typescript
+import {
+  withCorrelationContext,
+  getCorrelationContext,
+  extractCorrelationId,
+  createPropagationHeaders
+} from '@payloops/observability';
+
+// In HTTP middleware
+app.use((req, res, next) => {
+  const correlationId = extractCorrelationId(req.headers);
+
+  withCorrelationContext({ correlationId }, () => {
+    // All code in this context has access to correlationId
+    next();
+  });
+});
+
+// Later in your code
+const ctx = getCorrelationContext();
+console.log(ctx?.correlationId); // Available anywhere in the call stack
+
+// When calling downstream services
+const headers = createPropagationHeaders(ctx.correlationId);
+fetch('http://other-service/api', { headers });
+```
+
+### Metrics
+
+```typescript
+import {
+  recordPaymentAttempt,
+  recordPaymentAmount,
+  recordHttpRequest,
+  recordWorkflowStarted
+} from '@payloops/observability';
+
+// Record a payment attempt
+recordPaymentAttempt('stripe', 'USD', 'success');
+recordPaymentAmount(9999, 'stripe', 'USD');
+
+// Record HTTP request
+recordHttpRequest('POST', '/v1/orders', 201, 45.2);
+
+// Record workflow execution
+recordWorkflowStarted('PaymentWorkflow', 'stripe-payments');
+```
+
+## Available Exports
+
+### OpenTelemetry
+- `initTelemetry(config)` - Initialize OpenTelemetry SDK
+- `shutdownTelemetry()` - Gracefully shutdown telemetry
+
+### Logger
+- `logger` - Base Pino logger with trace context
+- `createActivityLogger(name, correlationId)` - Logger for Temporal activities
+- `createWorkflowLogger(workflowId, correlationId)` - Logger for workflows
+- `createRequestLogger(requestId, method, path)` - Logger for HTTP requests
+
+### Correlation Context
+- `getCorrelationContext()` - Get current context
+- `withCorrelationContext(ctx, fn)` - Run function with context
+- `generateCorrelationId()` - Generate new ID
+- `extractCorrelationId(headers)` - Extract from HTTP headers
+- `createPropagationHeaders(correlationId)` - Create headers for downstream calls
+- `CORRELATION_ID_HEADER` - Header name constant
+
+### Metrics
+| Metric | Type | Description |
+|--------|------|-------------|
+| `payments_total` | Counter | Payment attempts |
+| `payment_amount` | Histogram | Payment amounts |
+| `payment_latency_ms` | Histogram | Payment processing time |
+| `webhook_deliveries_total` | Counter | Webhook delivery attempts |
+| `webhook_latency_ms` | Histogram | Webhook delivery time |
+| `http_requests_total` | Counter | HTTP requests |
+| `http_request_latency_ms` | Histogram | HTTP request time |
+| `http_active_requests` | Gauge | Active HTTP requests |
+| `db_query_duration_ms` | Histogram | Database query time |
+| `workflow_started_total` | Counter | Workflows started |
+| `workflow_completed_total` | Counter | Workflows completed |
+| `workflow_failed_total` | Counter | Workflows failed |
+| `activity_latency_ms` | Histogram | Activity execution time |
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP endpoint | `http://localhost:4318` |
+| `OTEL_SERVICE_NAME` | Service name | `loop` |
+| `NODE_ENV` | Environment | `development` |

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import pino from 'pino';
+import * as _opentelemetry_api from '@opentelemetry/api';
+
+interface TelemetryConfig {
+    serviceName: string;
+    serviceVersion?: string;
+    otlpEndpoint?: string;
+    environment?: string;
+    enabledInstrumentations?: {
+        fs?: boolean;
+        http?: boolean;
+        pg?: boolean;
+    };
+}
+declare function initTelemetry(config: TelemetryConfig | string, serviceVersion?: string): NodeSDK;
+declare function shutdownTelemetry(): Promise<void>;
+
+/**
+ * Base logger with trace context mixin
+ */
+declare const logger: pino.Logger<never, boolean>;
+/**
+ * Create a child logger for a specific activity
+ */
+declare function createActivityLogger(activityName: string, correlationId?: string): pino.Logger<never, boolean>;
+/**
+ * Create a child logger for a specific workflow
+ */
+declare function createWorkflowLogger(workflowId: string, correlationId?: string): pino.Logger<never, boolean>;
+/**
+ * Create a child logger for HTTP requests
+ */
+declare function createRequestLogger(requestId: string, method: string, path: string): pino.Logger<never, boolean>;
+
+/**
+ * Correlation context for tracking requests across services
+ */
+interface CorrelationContext {
+    correlationId: string;
+    merchantId?: string;
+    orderId?: string;
+    workflowId?: string;
+}
+declare const CORRELATION_ID_HEADER = "X-Correlation-ID";
+declare const REQUEST_ID_HEADER = "X-Request-ID";
+/**
+ * Get the current correlation context
+ */
+declare function getCorrelationContext(): CorrelationContext | undefined;
+/**
+ * Run a function with a correlation context
+ */
+declare function withCorrelationContext<T>(ctx: CorrelationContext, fn: () => T): T;
+/**
+ * Run an async function with a correlation context
+ */
+declare function withCorrelationContextAsync<T>(ctx: CorrelationContext, fn: () => Promise<T>): Promise<T>;
+/**
+ * Generate a new correlation ID
+ */
+declare function generateCorrelationId(): string;
+/**
+ * Extract correlation ID from headers (case-insensitive)
+ */
+declare function extractCorrelationId(headers: Record<string, string | undefined>): string;
+/**
+ * Create headers for propagating correlation context to downstream services
+ */
+declare function createPropagationHeaders(correlationId: string): Record<string, string>;
+/**
+ * Create correlation context from Temporal workflow memo
+ */
+declare function createContextFromMemo(memo: Record<string, unknown>): CorrelationContext;
+
+declare const paymentCounter: _opentelemetry_api.Counter<_opentelemetry_api.Attributes>;
+declare const paymentAmountHistogram: _opentelemetry_api.Histogram<_opentelemetry_api.Attributes>;
+declare const paymentLatencyHistogram: _opentelemetry_api.Histogram<_opentelemetry_api.Attributes>;
+declare const webhookDeliveryCounter: _opentelemetry_api.Counter<_opentelemetry_api.Attributes>;
+declare const webhookLatencyHistogram: _opentelemetry_api.Histogram<_opentelemetry_api.Attributes>;
+declare const httpRequestCounter: _opentelemetry_api.Counter<_opentelemetry_api.Attributes>;
+declare const httpRequestLatencyHistogram: _opentelemetry_api.Histogram<_opentelemetry_api.Attributes>;
+declare const activeRequestsGauge: _opentelemetry_api.UpDownCounter<_opentelemetry_api.Attributes>;
+declare const dbQueryHistogram: _opentelemetry_api.Histogram<_opentelemetry_api.Attributes>;
+declare const dbConnectionGauge: _opentelemetry_api.UpDownCounter<_opentelemetry_api.Attributes>;
+declare const workflowStartedCounter: _opentelemetry_api.Counter<_opentelemetry_api.Attributes>;
+declare const workflowCompletedCounter: _opentelemetry_api.Counter<_opentelemetry_api.Attributes>;
+declare const workflowFailedCounter: _opentelemetry_api.Counter<_opentelemetry_api.Attributes>;
+declare const activityLatencyHistogram: _opentelemetry_api.Histogram<_opentelemetry_api.Attributes>;
+declare function recordPaymentAttempt(processor: string, currency: string, status: 'success' | 'failed' | 'pending'): void;
+declare function recordPaymentAmount(amount: number, processor: string, currency: string): void;
+declare function recordPaymentLatency(durationMs: number, processor: string, status: 'success' | 'failed'): void;
+declare function recordWebhookDelivery(status: 'success' | 'failed', attempt: number): void;
+declare function recordWebhookLatency(durationMs: number, status: 'success' | 'failed'): void;
+declare function recordHttpRequest(method: string, path: string, statusCode: number, durationMs: number): void;
+declare function recordWorkflowStarted(workflowType: string, taskQueue: string): void;
+declare function recordWorkflowCompleted(workflowType: string, taskQueue: string, durationMs: number): void;
+declare function recordWorkflowFailed(workflowType: string, taskQueue: string, errorType: string): void;
+declare function recordActivityLatency(activityType: string, durationMs: number, status: 'success' | 'failed'): void;
+
+export { CORRELATION_ID_HEADER, type CorrelationContext, REQUEST_ID_HEADER, type TelemetryConfig, activeRequestsGauge, activityLatencyHistogram, createActivityLogger, createContextFromMemo, createPropagationHeaders, createRequestLogger, createWorkflowLogger, dbConnectionGauge, dbQueryHistogram, extractCorrelationId, generateCorrelationId, getCorrelationContext, httpRequestCounter, httpRequestLatencyHistogram, initTelemetry, logger, paymentAmountHistogram, paymentCounter, paymentLatencyHistogram, recordActivityLatency, recordHttpRequest, recordPaymentAmount, recordPaymentAttempt, recordPaymentLatency, recordWebhookDelivery, recordWebhookLatency, recordWorkflowCompleted, recordWorkflowFailed, recordWorkflowStarted, shutdownTelemetry, webhookDeliveryCounter, webhookLatencyHistogram, withCorrelationContext, withCorrelationContextAsync, workflowCompletedCounter, workflowFailedCounter, workflowStartedCounter };

package/dist/index.js

@@ -0,0 +1,505 @@
+// src/lib/otel.ts
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
+
+// node_modules/@opentelemetry/resources/build/esm/Resource.js
+import { diag } from "@opentelemetry/api";
+import { SEMRESATTRS_SERVICE_NAME, SEMRESATTRS_TELEMETRY_SDK_LANGUAGE as SEMRESATTRS_TELEMETRY_SDK_LANGUAGE2, SEMRESATTRS_TELEMETRY_SDK_NAME as SEMRESATTRS_TELEMETRY_SDK_NAME2, SEMRESATTRS_TELEMETRY_SDK_VERSION as SEMRESATTRS_TELEMETRY_SDK_VERSION2 } from "@opentelemetry/semantic-conventions";
+
+// node_modules/@opentelemetry/core/build/esm/version.js
+var VERSION = "1.30.1";
+
+// node_modules/@opentelemetry/core/build/esm/platform/node/sdk-info.js
+import { SEMRESATTRS_TELEMETRY_SDK_NAME, SEMRESATTRS_PROCESS_RUNTIME_NAME, SEMRESATTRS_TELEMETRY_SDK_LANGUAGE, TELEMETRYSDKLANGUAGEVALUES_NODEJS, SEMRESATTRS_TELEMETRY_SDK_VERSION } from "@opentelemetry/semantic-conventions";
+var _a;
+var SDK_INFO = (_a = {}, _a[SEMRESATTRS_TELEMETRY_SDK_NAME] = "opentelemetry", _a[SEMRESATTRS_PROCESS_RUNTIME_NAME] = "node", _a[SEMRESATTRS_TELEMETRY_SDK_LANGUAGE] = TELEMETRYSDKLANGUAGEVALUES_NODEJS, _a[SEMRESATTRS_TELEMETRY_SDK_VERSION] = VERSION, _a);
+
+// node_modules/@opentelemetry/resources/build/esm/platform/node/default-service-name.js
+function defaultServiceName() {
+  return "unknown_service:" + process.argv0;
+}
+
+// node_modules/@opentelemetry/resources/build/esm/Resource.js
+var __assign = function() {
+  __assign = Object.assign || function(t) {
+    for (var s, i = 1, n = arguments.length; i < n; i++) {
+      s = arguments[i];
+      for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+        t[p] = s[p];
+    }
+    return t;
+  };
+  return __assign.apply(this, arguments);
+};
+var __awaiter = function(thisArg, _arguments, P, generator) {
+  function adopt(value) {
+    return value instanceof P ? value : new P(function(resolve) {
+      resolve(value);
+    });
+  }
+  return new (P || (P = Promise))(function(resolve, reject) {
+    function fulfilled(value) {
+      try {
+        step(generator.next(value));
+      } catch (e) {
+        reject(e);
+      }
+    }
+    function rejected(value) {
+      try {
+        step(generator["throw"](value));
+      } catch (e) {
+        reject(e);
+      }
+    }
+    function step(result) {
+      result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected);
+    }
+    step((generator = generator.apply(thisArg, _arguments || [])).next());
+  });
+};
+var __generator = function(thisArg, body) {
+  var _ = { label: 0, sent: function() {
+    if (t[0] & 1) throw t[1];
+    return t[1];
+  }, trys: [], ops: [] }, f, y, t, g;
+  return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() {
+    return this;
+  }), g;
+  function verb(n) {
+    return function(v) {
+      return step([n, v]);
+    };
+  }
+  function step(op) {
+    if (f) throw new TypeError("Generator is already executing.");
+    while (_) try {
+      if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+      if (y = 0, t) op = [op[0] & 2, t.value];
+      switch (op[0]) {
+        case 0:
+        case 1:
+          t = op;
+          break;
+        case 4:
+          _.label++;
+          return { value: op[1], done: false };
+        case 5:
+          _.label++;
+          y = op[1];
+          op = [0];
+          continue;
+        case 7:
+          op = _.ops.pop();
+          _.trys.pop();
+          continue;
+        default:
+          if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+            _ = 0;
+            continue;
+          }
+          if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+            _.label = op[1];
+            break;
+          }
+          if (op[0] === 6 && _.label < t[1]) {
+            _.label = t[1];
+            t = op;
+            break;
+          }
+          if (t && _.label < t[2]) {
+            _.label = t[2];
+            _.ops.push(op);
+            break;
+          }
+          if (t[2]) _.ops.pop();
+          _.trys.pop();
+          continue;
+      }
+      op = body.call(thisArg, _);
+    } catch (e) {
+      op = [6, e];
+      y = 0;
+    } finally {
+      f = t = 0;
+    }
+    if (op[0] & 5) throw op[1];
+    return { value: op[0] ? op[1] : void 0, done: true };
+  }
+};
+var __read = function(o, n) {
+  var m = typeof Symbol === "function" && o[Symbol.iterator];
+  if (!m) return o;
+  var i = m.call(o), r, ar = [], e;
+  try {
+    while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+  } catch (error) {
+    e = { error };
+  } finally {
+    try {
+      if (r && !r.done && (m = i["return"])) m.call(i);
+    } finally {
+      if (e) throw e.error;
+    }
+  }
+  return ar;
+};
+var Resource = (
+  /** @class */
+  (function() {
+    function Resource2(attributes, asyncAttributesPromise) {
+      var _this = this;
+      var _a2;
+      this._attributes = attributes;
+      this.asyncAttributesPending = asyncAttributesPromise != null;
+      this._syncAttributes = (_a2 = this._attributes) !== null && _a2 !== void 0 ? _a2 : {};
+      this._asyncAttributesPromise = asyncAttributesPromise === null || asyncAttributesPromise === void 0 ? void 0 : asyncAttributesPromise.then(function(asyncAttributes) {
+        _this._attributes = Object.assign({}, _this._attributes, asyncAttributes);
+        _this.asyncAttributesPending = false;
+        return asyncAttributes;
+      }, function(err) {
+        diag.debug("a resource's async attributes promise rejected: %s", err);
+        _this.asyncAttributesPending = false;
+        return {};
+      });
+    }
+    Resource2.empty = function() {
+      return Resource2.EMPTY;
+    };
+    Resource2.default = function() {
+      var _a2;
+      return new Resource2((_a2 = {}, _a2[SEMRESATTRS_SERVICE_NAME] = defaultServiceName(), _a2[SEMRESATTRS_TELEMETRY_SDK_LANGUAGE2] = SDK_INFO[SEMRESATTRS_TELEMETRY_SDK_LANGUAGE2], _a2[SEMRESATTRS_TELEMETRY_SDK_NAME2] = SDK_INFO[SEMRESATTRS_TELEMETRY_SDK_NAME2], _a2[SEMRESATTRS_TELEMETRY_SDK_VERSION2] = SDK_INFO[SEMRESATTRS_TELEMETRY_SDK_VERSION2], _a2));
+    };
+    Object.defineProperty(Resource2.prototype, "attributes", {
+      get: function() {
+        var _a2;
+        if (this.asyncAttributesPending) {
+          diag.error("Accessing resource attributes before async attributes settled");
+        }
+        return (_a2 = this._attributes) !== null && _a2 !== void 0 ? _a2 : {};
+      },
+      enumerable: false,
+      configurable: true
+    });
+    Resource2.prototype.waitForAsyncAttributes = function() {
+      return __awaiter(this, void 0, void 0, function() {
+        return __generator(this, function(_a2) {
+          switch (_a2.label) {
+            case 0:
+              if (!this.asyncAttributesPending) return [3, 2];
+              return [4, this._asyncAttributesPromise];
+            case 1:
+              _a2.sent();
+              _a2.label = 2;
+            case 2:
+              return [
+                2
+                /*return*/
+              ];
+          }
+        });
+      });
+    };
+    Resource2.prototype.merge = function(other) {
+      var _this = this;
+      var _a2;
+      if (!other)
+        return this;
+      var mergedSyncAttributes = __assign(__assign({}, this._syncAttributes), (_a2 = other._syncAttributes) !== null && _a2 !== void 0 ? _a2 : other.attributes);
+      if (!this._asyncAttributesPromise && !other._asyncAttributesPromise) {
+        return new Resource2(mergedSyncAttributes);
+      }
+      var mergedAttributesPromise = Promise.all([
+        this._asyncAttributesPromise,
+        other._asyncAttributesPromise
+      ]).then(function(_a3) {
+        var _b;
+        var _c = __read(_a3, 2), thisAsyncAttributes = _c[0], otherAsyncAttributes = _c[1];
+        return __assign(__assign(__assign(__assign({}, _this._syncAttributes), thisAsyncAttributes), (_b = other._syncAttributes) !== null && _b !== void 0 ? _b : other.attributes), otherAsyncAttributes);
+      });
+      return new Resource2(mergedSyncAttributes, mergedAttributesPromise);
+    };
+    Resource2.EMPTY = new Resource2({});
+    return Resource2;
+  })()
+);
+
+// src/lib/otel.ts
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
+import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+var sdk = null;
+function initTelemetry(config, serviceVersion = "0.0.1") {
+  if (sdk) return sdk;
+  const cfg = typeof config === "string" ? { serviceName: config, serviceVersion } : config;
+  const otlpEndpoint = cfg.otlpEndpoint || process.env.OTEL_EXPORTER_OTLP_ENDPOINT || "http://localhost:4318";
+  const environment = cfg.environment || process.env.NODE_ENV || "development";
+  sdk = new NodeSDK({
+    resource: new Resource({
+      [ATTR_SERVICE_NAME]: cfg.serviceName,
+      [ATTR_SERVICE_VERSION]: cfg.serviceVersion || "0.0.1",
+      "deployment.environment": environment
+    }),
+    traceExporter: new OTLPTraceExporter({
+      url: `${otlpEndpoint}/v1/traces`
+    }),
+    metricReader: new PeriodicExportingMetricReader({
+      exporter: new OTLPMetricExporter({
+        url: `${otlpEndpoint}/v1/metrics`
+      }),
+      exportIntervalMillis: 3e4
+    }),
+    instrumentations: [
+      getNodeAutoInstrumentations({
+        "@opentelemetry/instrumentation-fs": { enabled: cfg.enabledInstrumentations?.fs ?? false },
+        "@opentelemetry/instrumentation-http": { enabled: cfg.enabledInstrumentations?.http ?? true },
+        "@opentelemetry/instrumentation-pg": { enabled: cfg.enabledInstrumentations?.pg ?? true }
+      })
+    ]
+  });
+  sdk.start();
+  process.on("SIGTERM", () => {
+    sdk?.shutdown().then(() => console.log("Telemetry shut down")).catch((err) => console.error("Telemetry shutdown error", err));
+  });
+  return sdk;
+}
+function shutdownTelemetry() {
+  if (!sdk) return Promise.resolve();
+  return sdk.shutdown();
+}
+
+// src/lib/logger.ts
+import pino from "pino";
+import { trace } from "@opentelemetry/api";
+
+// src/lib/context.ts
+import { AsyncLocalStorage } from "async_hooks";
+import { nanoid } from "nanoid";
+import { context, propagation } from "@opentelemetry/api";
+var correlationStorage = new AsyncLocalStorage();
+var CORRELATION_ID_HEADER = "X-Correlation-ID";
+var REQUEST_ID_HEADER = "X-Request-ID";
+function getCorrelationContext() {
+  return correlationStorage.getStore();
+}
+function withCorrelationContext(ctx, fn) {
+  return correlationStorage.run(ctx, fn);
+}
+async function withCorrelationContextAsync(ctx, fn) {
+  return correlationStorage.run(ctx, fn);
+}
+function generateCorrelationId() {
+  return nanoid(21);
+}
+function extractCorrelationId(headers) {
+  const normalizedHeaders = {};
+  for (const [key, value] of Object.entries(headers)) {
+    normalizedHeaders[key.toLowerCase()] = value;
+  }
+  return normalizedHeaders[CORRELATION_ID_HEADER.toLowerCase()] || normalizedHeaders[REQUEST_ID_HEADER.toLowerCase()] || generateCorrelationId();
+}
+function createPropagationHeaders(correlationId) {
+  const headers = {
+    [CORRELATION_ID_HEADER]: correlationId
+  };
+  propagation.inject(context.active(), headers);
+  return headers;
+}
+function createContextFromMemo(memo) {
+  return {
+    correlationId: memo.correlationId || generateCorrelationId(),
+    merchantId: memo.merchantId,
+    orderId: memo.orderId,
+    workflowId: memo.workflowId
+  };
+}
+
+// src/lib/logger.ts
+var NODE_ENV = process.env.NODE_ENV || "development";
+var SERVICE_NAME = process.env.OTEL_SERVICE_NAME || "loop";
+var traceMixin = () => {
+  const mixinData = {};
+  const span = trace.getActiveSpan();
+  if (span) {
+    const spanContext = span.spanContext();
+    mixinData.trace_id = spanContext.traceId;
+    mixinData.span_id = spanContext.spanId;
+  }
+  const correlationCtx = getCorrelationContext();
+  if (correlationCtx) {
+    mixinData.correlation_id = correlationCtx.correlationId;
+    if (correlationCtx.merchantId) mixinData.merchant_id = correlationCtx.merchantId;
+    if (correlationCtx.orderId) mixinData.order_id = correlationCtx.orderId;
+    if (correlationCtx.workflowId) mixinData.workflow_id = correlationCtx.workflowId;
+  }
+  return mixinData;
+};
+var logger = pino({
+  level: NODE_ENV === "production" ? "info" : "debug",
+  mixin: traceMixin,
+  base: {
+    service: SERVICE_NAME,
+    env: NODE_ENV
+  },
+  timestamp: pino.stdTimeFunctions.isoTime,
+  transport: NODE_ENV !== "production" ? { target: "pino-pretty", options: { colorize: true } } : void 0
+});
+function createActivityLogger(activityName, correlationId) {
+  return logger.child({
+    activity: activityName,
+    correlationId
+  });
+}
+function createWorkflowLogger(workflowId, correlationId) {
+  return logger.child({
+    workflowId,
+    correlationId
+  });
+}
+function createRequestLogger(requestId, method, path) {
+  return logger.child({
+    requestId,
+    method,
+    path
+  });
+}
+
+// src/lib/metrics.ts
+import { metrics, ValueType } from "@opentelemetry/api";
+var meter = metrics.getMeter("payloops");
+var paymentCounter = meter.createCounter("payments_total", {
+  description: "Total number of payment attempts",
+  valueType: ValueType.INT
+});
+var paymentAmountHistogram = meter.createHistogram("payment_amount", {
+  description: "Distribution of payment amounts",
+  unit: "cents",
+  valueType: ValueType.INT
+});
+var paymentLatencyHistogram = meter.createHistogram("payment_latency_ms", {
+  description: "Payment processing latency",
+  unit: "ms",
+  valueType: ValueType.DOUBLE
+});
+var webhookDeliveryCounter = meter.createCounter("webhook_deliveries_total", {
+  description: "Total webhook delivery attempts",
+  valueType: ValueType.INT
+});
+var webhookLatencyHistogram = meter.createHistogram("webhook_latency_ms", {
+  description: "Webhook delivery latency",
+  unit: "ms",
+  valueType: ValueType.DOUBLE
+});
+var httpRequestCounter = meter.createCounter("http_requests_total", {
+  description: "Total HTTP requests",
+  valueType: ValueType.INT
+});
+var httpRequestLatencyHistogram = meter.createHistogram("http_request_latency_ms", {
+  description: "HTTP request latency",
+  unit: "ms",
+  valueType: ValueType.DOUBLE
+});
+var activeRequestsGauge = meter.createUpDownCounter("http_active_requests", {
+  description: "Number of active HTTP requests",
+  valueType: ValueType.INT
+});
+var dbQueryHistogram = meter.createHistogram("db_query_duration_ms", {
+  description: "Database query duration",
+  unit: "ms",
+  valueType: ValueType.DOUBLE
+});
+var dbConnectionGauge = meter.createUpDownCounter("db_connections_active", {
+  description: "Number of active database connections",
+  valueType: ValueType.INT
+});
+var workflowStartedCounter = meter.createCounter("workflow_started_total", {
+  description: "Total workflows started",
+  valueType: ValueType.INT
+});
+var workflowCompletedCounter = meter.createCounter("workflow_completed_total", {
+  description: "Total workflows completed",
+  valueType: ValueType.INT
+});
+var workflowFailedCounter = meter.createCounter("workflow_failed_total", {
+  description: "Total workflows failed",
+  valueType: ValueType.INT
+});
+var activityLatencyHistogram = meter.createHistogram("activity_latency_ms", {
+  description: "Activity execution latency",
+  unit: "ms",
+  valueType: ValueType.DOUBLE
+});
+function recordPaymentAttempt(processor, currency, status) {
+  paymentCounter.add(1, { processor, currency, status });
+}
+function recordPaymentAmount(amount, processor, currency) {
+  paymentAmountHistogram.record(amount, { processor, currency });
+}
+function recordPaymentLatency(durationMs, processor, status) {
+  paymentLatencyHistogram.record(durationMs, { processor, status });
+}
+function recordWebhookDelivery(status, attempt) {
+  webhookDeliveryCounter.add(1, { status, attempt: String(attempt) });
+}
+function recordWebhookLatency(durationMs, status) {
+  webhookLatencyHistogram.record(durationMs, { status });
+}
+function recordHttpRequest(method, path, statusCode, durationMs) {
+  const statusClass = `${Math.floor(statusCode / 100)}xx`;
+  httpRequestCounter.add(1, { method, path, status_code: String(statusCode), status_class: statusClass });
+  httpRequestLatencyHistogram.record(durationMs, { method, path, status_class: statusClass });
+}
+function recordWorkflowStarted(workflowType, taskQueue) {
+  workflowStartedCounter.add(1, { workflow_type: workflowType, task_queue: taskQueue });
+}
+function recordWorkflowCompleted(workflowType, taskQueue, durationMs) {
+  workflowCompletedCounter.add(1, { workflow_type: workflowType, task_queue: taskQueue });
+}
+function recordWorkflowFailed(workflowType, taskQueue, errorType) {
+  workflowFailedCounter.add(1, { workflow_type: workflowType, task_queue: taskQueue, error_type: errorType });
+}
+function recordActivityLatency(activityType, durationMs, status) {
+  activityLatencyHistogram.record(durationMs, { activity_type: activityType, status });
+}
+export {
+  CORRELATION_ID_HEADER,
+  REQUEST_ID_HEADER,
+  activeRequestsGauge,
+  activityLatencyHistogram,
+  createActivityLogger,
+  createContextFromMemo,
+  createPropagationHeaders,
+  createRequestLogger,
+  createWorkflowLogger,
+  dbConnectionGauge,
+  dbQueryHistogram,
+  extractCorrelationId,
+  generateCorrelationId,
+  getCorrelationContext,
+  httpRequestCounter,
+  httpRequestLatencyHistogram,
+  initTelemetry,
+  logger,
+  paymentAmountHistogram,
+  paymentCounter,
+  paymentLatencyHistogram,
+  recordActivityLatency,
+  recordHttpRequest,
+  recordPaymentAmount,
+  recordPaymentAttempt,
+  recordPaymentLatency,
+  recordWebhookDelivery,
+  recordWebhookLatency,
+  recordWorkflowCompleted,
+  recordWorkflowFailed,
+  recordWorkflowStarted,
+  shutdownTelemetry,
+  webhookDeliveryCounter,
+  webhookLatencyHistogram,
+  withCorrelationContext,
+  withCorrelationContextAsync,
+  workflowCompletedCounter,
+  workflowFailedCounter,
+  workflowStartedCounter
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@payloops/observability",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.53.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.57.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.57.0",
+    "@opentelemetry/sdk-metrics": "^1.30.1",
+    "@opentelemetry/sdk-node": "^0.57.0",
+    "@opentelemetry/semantic-conventions": "^1.28.0",
+    "nanoid": "^5.0.9",
+    "pino": "^9.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "eslint": "^9.0.0",
+    "pino-pretty": "^13.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.9.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+// OpenTelemetry
+export { initTelemetry, shutdownTelemetry, type TelemetryConfig } from './lib/otel';
+
+// Logger
+export { logger, createActivityLogger, createWorkflowLogger, createRequestLogger } from './lib/logger';
+
+// Correlation Context
+export {
+  getCorrelationContext,
+  withCorrelationContext,
+  withCorrelationContextAsync,
+  generateCorrelationId,
+  extractCorrelationId,
+  createPropagationHeaders,
+  createContextFromMemo,
+  CORRELATION_ID_HEADER,
+  REQUEST_ID_HEADER,
+  type CorrelationContext
+} from './lib/context';
+
+// Metrics
+export {
+  // Payment metrics
+  paymentCounter,
+  paymentAmountHistogram,
+  paymentLatencyHistogram,
+  recordPaymentAttempt,
+  recordPaymentAmount,
+  recordPaymentLatency,
+
+  // Webhook metrics
+  webhookDeliveryCounter,
+  webhookLatencyHistogram,
+  recordWebhookDelivery,
+  recordWebhookLatency,
+
+  // HTTP metrics
+  httpRequestCounter,
+  httpRequestLatencyHistogram,
+  activeRequestsGauge,
+  recordHttpRequest,
+
+  // Database metrics
+  dbQueryHistogram,
+  dbConnectionGauge,
+
+  // Workflow metrics
+  workflowStartedCounter,
+  workflowCompletedCounter,
+  workflowFailedCounter,
+  activityLatencyHistogram,
+  recordWorkflowStarted,
+  recordWorkflowCompleted,
+  recordWorkflowFailed,
+  recordActivityLatency
+} from './lib/metrics';

package/src/lib/context.ts

@@ -0,0 +1,90 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import { nanoid } from 'nanoid';
+import { context, propagation } from '@opentelemetry/api';
+
+/**
+ * Correlation context for tracking requests across services
+ */
+export interface CorrelationContext {
+  correlationId: string;
+  merchantId?: string;
+  orderId?: string;
+  workflowId?: string;
+}
+
+const correlationStorage = new AsyncLocalStorage<CorrelationContext>();
+
+// Standard headers for correlation
+export const CORRELATION_ID_HEADER = 'X-Correlation-ID';
+export const REQUEST_ID_HEADER = 'X-Request-ID';
+
+/**
+ * Get the current correlation context
+ */
+export function getCorrelationContext(): CorrelationContext | undefined {
+  return correlationStorage.getStore();
+}
+
+/**
+ * Run a function with a correlation context
+ */
+export function withCorrelationContext<T>(ctx: CorrelationContext, fn: () => T): T {
+  return correlationStorage.run(ctx, fn);
+}
+
+/**
+ * Run an async function with a correlation context
+ */
+export async function withCorrelationContextAsync<T>(ctx: CorrelationContext, fn: () => Promise<T>): Promise<T> {
+  return correlationStorage.run(ctx, fn);
+}
+
+/**
+ * Generate a new correlation ID
+ */
+export function generateCorrelationId(): string {
+  return nanoid(21);
+}
+
+/**
+ * Extract correlation ID from headers (case-insensitive)
+ */
+export function extractCorrelationId(headers: Record<string, string | undefined>): string {
+  // Normalize header keys to lowercase for lookup
+  const normalizedHeaders: Record<string, string | undefined> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    normalizedHeaders[key.toLowerCase()] = value;
+  }
+
+  return (
+    normalizedHeaders[CORRELATION_ID_HEADER.toLowerCase()] ||
+    normalizedHeaders[REQUEST_ID_HEADER.toLowerCase()] ||
+    generateCorrelationId()
+  );
+}
+
+/**
+ * Create headers for propagating correlation context to downstream services
+ */
+export function createPropagationHeaders(correlationId: string): Record<string, string> {
+  const headers: Record<string, string> = {
+    [CORRELATION_ID_HEADER]: correlationId
+  };
+
+  // Inject OpenTelemetry trace context
+  propagation.inject(context.active(), headers);
+
+  return headers;
+}
+
+/**
+ * Create correlation context from Temporal workflow memo
+ */
+export function createContextFromMemo(memo: Record<string, unknown>): CorrelationContext {
+  return {
+    correlationId: (memo.correlationId as string) || generateCorrelationId(),
+    merchantId: memo.merchantId as string | undefined,
+    orderId: memo.orderId as string | undefined,
+    workflowId: memo.workflowId as string | undefined
+  };
+}

package/src/lib/logger.ts

@@ -0,0 +1,77 @@
+import pino from 'pino';
+import { trace } from '@opentelemetry/api';
+import { getCorrelationContext } from './context';
+
+const NODE_ENV = process.env.NODE_ENV || 'development';
+const SERVICE_NAME = process.env.OTEL_SERVICE_NAME || 'loop';
+
+/**
+ * Mixin that adds trace context to every log entry
+ */
+const traceMixin = () => {
+  const mixinData: Record<string, string | undefined> = {};
+
+  // Add OpenTelemetry trace context
+  const span = trace.getActiveSpan();
+  if (span) {
+    const spanContext = span.spanContext();
+    mixinData.trace_id = spanContext.traceId;
+    mixinData.span_id = spanContext.spanId;
+  }
+
+  // Add correlation context
+  const correlationCtx = getCorrelationContext();
+  if (correlationCtx) {
+    mixinData.correlation_id = correlationCtx.correlationId;
+    if (correlationCtx.merchantId) mixinData.merchant_id = correlationCtx.merchantId;
+    if (correlationCtx.orderId) mixinData.order_id = correlationCtx.orderId;
+    if (correlationCtx.workflowId) mixinData.workflow_id = correlationCtx.workflowId;
+  }
+
+  return mixinData;
+};
+
+/**
+ * Base logger with trace context mixin
+ */
+export const logger = pino({
+  level: NODE_ENV === 'production' ? 'info' : 'debug',
+  mixin: traceMixin,
+  base: {
+    service: SERVICE_NAME,
+    env: NODE_ENV
+  },
+  timestamp: pino.stdTimeFunctions.isoTime,
+  transport: NODE_ENV !== 'production' ? { target: 'pino-pretty', options: { colorize: true } } : undefined
+});
+
+/**
+ * Create a child logger for a specific activity
+ */
+export function createActivityLogger(activityName: string, correlationId?: string) {
+  return logger.child({
+    activity: activityName,
+    correlationId
+  });
+}
+
+/**
+ * Create a child logger for a specific workflow
+ */
+export function createWorkflowLogger(workflowId: string, correlationId?: string) {
+  return logger.child({
+    workflowId,
+    correlationId
+  });
+}
+
+/**
+ * Create a child logger for HTTP requests
+ */
+export function createRequestLogger(requestId: string, method: string, path: string) {
+  return logger.child({
+    requestId,
+    method,
+    path
+  });
+}

package/src/lib/metrics.ts

@@ -0,0 +1,146 @@
+import { metrics, ValueType } from '@opentelemetry/api';
+
+// Create a meter for the application
+const meter = metrics.getMeter('payloops');
+
+// =============================================================================
+// Payment Metrics
+// =============================================================================
+
+export const paymentCounter = meter.createCounter('payments_total', {
+  description: 'Total number of payment attempts',
+  valueType: ValueType.INT
+});
+
+export const paymentAmountHistogram = meter.createHistogram('payment_amount', {
+  description: 'Distribution of payment amounts',
+  unit: 'cents',
+  valueType: ValueType.INT
+});
+
+export const paymentLatencyHistogram = meter.createHistogram('payment_latency_ms', {
+  description: 'Payment processing latency',
+  unit: 'ms',
+  valueType: ValueType.DOUBLE
+});
+
+// =============================================================================
+// Webhook Metrics
+// =============================================================================
+
+export const webhookDeliveryCounter = meter.createCounter('webhook_deliveries_total', {
+  description: 'Total webhook delivery attempts',
+  valueType: ValueType.INT
+});
+
+export const webhookLatencyHistogram = meter.createHistogram('webhook_latency_ms', {
+  description: 'Webhook delivery latency',
+  unit: 'ms',
+  valueType: ValueType.DOUBLE
+});
+
+// =============================================================================
+// HTTP Metrics
+// =============================================================================
+
+export const httpRequestCounter = meter.createCounter('http_requests_total', {
+  description: 'Total HTTP requests',
+  valueType: ValueType.INT
+});
+
+export const httpRequestLatencyHistogram = meter.createHistogram('http_request_latency_ms', {
+  description: 'HTTP request latency',
+  unit: 'ms',
+  valueType: ValueType.DOUBLE
+});
+
+export const activeRequestsGauge = meter.createUpDownCounter('http_active_requests', {
+  description: 'Number of active HTTP requests',
+  valueType: ValueType.INT
+});
+
+// =============================================================================
+// Database Metrics
+// =============================================================================
+
+export const dbQueryHistogram = meter.createHistogram('db_query_duration_ms', {
+  description: 'Database query duration',
+  unit: 'ms',
+  valueType: ValueType.DOUBLE
+});
+
+export const dbConnectionGauge = meter.createUpDownCounter('db_connections_active', {
+  description: 'Number of active database connections',
+  valueType: ValueType.INT
+});
+
+// =============================================================================
+// Temporal Workflow Metrics
+// =============================================================================
+
+export const workflowStartedCounter = meter.createCounter('workflow_started_total', {
+  description: 'Total workflows started',
+  valueType: ValueType.INT
+});
+
+export const workflowCompletedCounter = meter.createCounter('workflow_completed_total', {
+  description: 'Total workflows completed',
+  valueType: ValueType.INT
+});
+
+export const workflowFailedCounter = meter.createCounter('workflow_failed_total', {
+  description: 'Total workflows failed',
+  valueType: ValueType.INT
+});
+
+export const activityLatencyHistogram = meter.createHistogram('activity_latency_ms', {
+  description: 'Activity execution latency',
+  unit: 'ms',
+  valueType: ValueType.DOUBLE
+});
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+export function recordPaymentAttempt(processor: string, currency: string, status: 'success' | 'failed' | 'pending') {
+  paymentCounter.add(1, { processor, currency, status });
+}
+
+export function recordPaymentAmount(amount: number, processor: string, currency: string) {
+  paymentAmountHistogram.record(amount, { processor, currency });
+}
+
+export function recordPaymentLatency(durationMs: number, processor: string, status: 'success' | 'failed') {
+  paymentLatencyHistogram.record(durationMs, { processor, status });
+}
+
+export function recordWebhookDelivery(status: 'success' | 'failed', attempt: number) {
+  webhookDeliveryCounter.add(1, { status, attempt: String(attempt) });
+}
+
+export function recordWebhookLatency(durationMs: number, status: 'success' | 'failed') {
+  webhookLatencyHistogram.record(durationMs, { status });
+}
+
+export function recordHttpRequest(method: string, path: string, statusCode: number, durationMs: number) {
+  const statusClass = `${Math.floor(statusCode / 100)}xx`;
+  httpRequestCounter.add(1, { method, path, status_code: String(statusCode), status_class: statusClass });
+  httpRequestLatencyHistogram.record(durationMs, { method, path, status_class: statusClass });
+}
+
+export function recordWorkflowStarted(workflowType: string, taskQueue: string) {
+  workflowStartedCounter.add(1, { workflow_type: workflowType, task_queue: taskQueue });
+}
+
+export function recordWorkflowCompleted(workflowType: string, taskQueue: string, durationMs: number) {
+  workflowCompletedCounter.add(1, { workflow_type: workflowType, task_queue: taskQueue });
+}
+
+export function recordWorkflowFailed(workflowType: string, taskQueue: string, errorType: string) {
+  workflowFailedCounter.add(1, { workflow_type: workflowType, task_queue: taskQueue, error_type: errorType });
+}
+
+export function recordActivityLatency(activityType: string, durationMs: number, status: 'success' | 'failed') {
+  activityLatencyHistogram.record(durationMs, { activity_type: activityType, status });
+}

package/src/lib/otel.ts

@@ -0,0 +1,75 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { Resource } from '@opentelemetry/resources';
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
+import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
+
+let sdk: NodeSDK | null = null;
+
+export interface TelemetryConfig {
+  serviceName: string;
+  serviceVersion?: string;
+  otlpEndpoint?: string;
+  environment?: string;
+  enabledInstrumentations?: {
+    fs?: boolean;
+    http?: boolean;
+    pg?: boolean;
+  };
+}
+
+export function initTelemetry(config: TelemetryConfig | string, serviceVersion = '0.0.1'): NodeSDK {
+  if (sdk) return sdk;
+
+  // Support both string (legacy) and config object
+  const cfg: TelemetryConfig =
+    typeof config === 'string' ? { serviceName: config, serviceVersion } : config;
+
+  const otlpEndpoint = cfg.otlpEndpoint || process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318';
+  const environment = cfg.environment || process.env.NODE_ENV || 'development';
+
+  sdk = new NodeSDK({
+    resource: new Resource({
+      [ATTR_SERVICE_NAME]: cfg.serviceName,
+      [ATTR_SERVICE_VERSION]: cfg.serviceVersion || '0.0.1',
+      'deployment.environment': environment
+    }),
+
+    traceExporter: new OTLPTraceExporter({
+      url: `${otlpEndpoint}/v1/traces`
+    }),
+
+    metricReader: new PeriodicExportingMetricReader({
+      exporter: new OTLPMetricExporter({
+        url: `${otlpEndpoint}/v1/metrics`
+      }),
+      exportIntervalMillis: 30000
+    }),
+
+    instrumentations: [
+      getNodeAutoInstrumentations({
+        '@opentelemetry/instrumentation-fs': { enabled: cfg.enabledInstrumentations?.fs ?? false },
+        '@opentelemetry/instrumentation-http': { enabled: cfg.enabledInstrumentations?.http ?? true },
+        '@opentelemetry/instrumentation-pg': { enabled: cfg.enabledInstrumentations?.pg ?? true }
+      })
+    ]
+  });
+
+  sdk.start();
+
+  process.on('SIGTERM', () => {
+    sdk
+      ?.shutdown()
+      .then(() => console.log('Telemetry shut down'))
+      .catch((err) => console.error('Telemetry shutdown error', err));
+  });
+
+  return sdk;
+}
+
+export function shutdownTelemetry(): Promise<void> {
+  if (!sdk) return Promise.resolve();
+  return sdk.shutdown();
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}