@manifest-cyber/observability-ts 0.2.11 → 0.2.12

package/README.md

@@ -299,6 +299,36 @@ extractMessageTraceContext(message.MessageAttributes);
 | `OTEL_TRACING_ENABLED` | Enable/disable tracing | `true` |
 | `ENV` | Environment (dev/staging/prod) | `'development'` |
 
+## Process Exit Interceptor
+
+When tracing is enabled, `process.exit()` is automatically intercepted to flush tracing data before termination (default: enabled, 2s timeout). This prevents telemetry loss on abrupt exits.
+
+```typescript
+import { initObservability } from '@manifest-cyber/observability-ts';
+
+await initObservability({
+  serviceName: 'my-service',
+  interceptProcessExit: true,  // default: true
+  exitFlushTimeoutMs: 2000,    // default: 2000ms
+});
+
+// Tracing automatically flushed on exit
+if (failed) process.exit(1);
+```
+
+**Configuration:**
+- `interceptProcessExit: boolean` - Enable/disable (default: `true`)
+- `exitFlushTimeoutMs: number` - Flush timeout in ms (default: `2000`)
+- `logger: Logger` - Optional logger for diagnostics
+
+**To disable:**
+```typescript
+await initObservability({
+  serviceName: 'my-service',
+  interceptProcessExit: false,
+});
+```
+
 ## Example: Express API
 
 ```typescript
@@ -360,6 +390,43 @@ app.get('/api/users/:id', async (req, res) => {
 app.listen(3000);
 ```
 
+## Migration from prom-client (v0.2.x → v0.3.x)
+
+v0.3.0 migrates from `prom-client` to OpenTelemetry SDK for metrics.
+
+### Breaking Changes
+
+| Change | Before | After |
+|--------|--------|-------|
+| `startMetricsServer()` | Sync | Async (`await`) |
+| `getRegistry()` / `resetRegistry()` | Exported | Removed |
+| `reset()` / `remove()` on metrics | Functional | No-op (API compat) |
+| prom-client type re-exports | Available | Removed |
+
+### New: Auto-instrumentation
+
+```typescript
+await initObservability({
+  serviceName: 'my-api',
+  autoInstrument: ['http', 'express', 'mongo'],
+});
+```
+
+### Optional Peer Dependencies
+
+```bash
+# Runtime metrics
+npm install @opentelemetry/host-metrics @opentelemetry/instrumentation-runtime-node
+
+# OTLP export (choose gRPC or HTTP)
+npm install @opentelemetry/exporter-metrics-otlp-grpc
+# or
+npm install @opentelemetry/exporter-metrics-otlp-http
+
+# Auto-instrumentation (as needed)
+npm install @opentelemetry/instrumentation-http @opentelemetry/instrumentation-express
+```
+
 ## Migration from @manifest-cyber/metrics
 
 ```bash

package/dist/index.d.ts

@@ -41,13 +41,13 @@
  * import { initTracing } from '@manifest-cyber/observability-ts/tracing';
  * ```
  */
-export { getRegistry, resetRegistry } from './metrics/registry';
+export { initMetricsProvider, getSharedMeterProvider, getSharedResource, getMeter, } from './metrics/provider';
+export type { MetricsProviderOptions, MetricsProviderInitResult, AutoInstrumentKey, } from './metrics/provider';
 export { startMetricsServer } from './metrics/server';
 export type { MetricsServerOptions } from './metrics/server';
 export { createCounter, createHistogram, createGauge, BUCKETS, ENV_KEY_SERVICE_NAME, } from './metrics/builders';
-export type { HistogramConfig } from './metrics/builders';
+export type { HistogramConfig, ServiceCounter, ServiceHistogram, ServiceGauge, } from './metrics/builders';
 export { Timer, MetricsContext, instrumentAsync, trackOperation, } from './metrics/instrumentation';
-export type { Counter, Histogram, Gauge, Registry } from 'prom-client';
 export { initTracing, isTracingInitialized, getTracerProvider, shutdownTracing, } from './tracing/setup';
 export { getTracer, createSpan, withSpan, withSpanResult, getCurrentSpan, getCurrentTraceId, getCurrentSpanId, addSpanEvent, setSpanAttributes, recordException, withActiveSpan, withActiveSpanAsync, } from './tracing/spans';
 export { injectTraceContext, extractTraceContext, getTraceparent, parseTraceparent, createContextFromTraceparent, createMessageTraceContext, extractMessageTraceContext, withExtractedContext, withExtractedContextAsync, } from './tracing/context';
@@ -57,4 +57,6 @@ export type { ServiceMetricsConfig, MetricLabels, DurationMetricOptions, Logger,
 export type { TracingConfig, ExporterConfig, SamplingConfig, SpanOptions, TracedResult, HttpSpanAttributes, DbSpanAttributes, MessagingSpanAttributes, TraceContext, } from './tracing/types';
 export { initObservability } from './init';
 export type { InitObservabilityConfig, InitObservabilityResult } from './init';
+export type { MeterProvider } from '@opentelemetry/sdk-metrics';
+export type { Meter } from '@opentelemetry/api';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAOH,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAG7D,OAAO,EACL,aAAa,EACb,eAAe,EACf,WAAW,EACX,OAAO,EACP,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG1D,OAAO,EACL,KAAK,EACL,cAAc,EACd,eAAe,EACf,cAAc,GACf,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAOvE,OAAO,EACL,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,SAAS,EACT,UAAU,EACV,QAAQ,EACR,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,4BAA4B,EAC5B,yBAAyB,EACzB,0BAA0B,EAC1B,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAM9D,YAAY,EACV,oBAAoB,EACpB,YAAY,EACZ,qBAAqB,EACrB,MAAM,GACP,MAAM,SAAS,CAAC;AAEjB,YAAY,EACV,aAAa,EACb,cAAc,EACd,cAAc,EACd,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACvB,YAAY,GACb,MAAM,iBAAiB,CAAC;AAMzB,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAC3C,YAAY,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAOH,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,EACjB,QAAQ,GACT,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,sBAAsB,EACtB,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAG7D,OAAO,EACL,aAAa,EACb,eAAe,EACf,WAAW,EACX,OAAO,EACP,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,KAAK,EACL,cAAc,EACd,eAAe,EACf,cAAc,GACf,MAAM,2BAA2B,CAAC;AAOnC,OAAO,EACL,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,SAAS,EACT,UAAU,EACV,QAAQ,EACR,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,4BAA4B,EAC5B,yBAAyB,EACzB,0BAA0B,EAC1B,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAM9D,YAAY,EACV,oBAAoB,EACpB,YAAY,EACZ,qBAAqB,EACrB,MAAM,GACP,MAAM,SAAS,CAAC;AAEjB,YAAY,EACV,aAAa,EACb,cAAc,EACd,cAAc,EACd,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACvB,YAAY,GACb,MAAM,iBAAiB,CAAC;AAMzB,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAC3C,YAAY,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAC;AAG/E,YAAY,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,YAAY,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -43,14 +43,16 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.initObservability = exports.SpanKind = exports.SpanStatusCode = exports.withExtractedContextAsync = exports.withExtractedContext = exports.extractMessageTraceContext = exports.createMessageTraceContext = exports.createContextFromTraceparent = exports.parseTraceparent = exports.getTraceparent = exports.extractTraceContext = exports.injectTraceContext = exports.withActiveSpanAsync = exports.withActiveSpan = exports.recordException = exports.setSpanAttributes = exports.addSpanEvent = exports.getCurrentSpanId = exports.getCurrentTraceId = exports.getCurrentSpan = exports.withSpanResult = exports.withSpan = exports.createSpan = exports.getTracer = exports.shutdownTracing = exports.getTracerProvider = exports.isTracingInitialized = exports.initTracing = exports.trackOperation = exports.instrumentAsync = exports.MetricsContext = exports.Timer = exports.ENV_KEY_SERVICE_NAME = exports.BUCKETS = exports.createGauge = exports.createHistogram = exports.createCounter = exports.startMetricsServer = exports.resetRegistry = exports.getRegistry = void 0;
+exports.initObservability = exports.SpanKind = exports.SpanStatusCode = exports.withExtractedContextAsync = exports.withExtractedContext = exports.extractMessageTraceContext = exports.createMessageTraceContext = exports.createContextFromTraceparent = exports.parseTraceparent = exports.getTraceparent = exports.extractTraceContext = exports.injectTraceContext = exports.withActiveSpanAsync = exports.withActiveSpan = exports.recordException = exports.setSpanAttributes = exports.addSpanEvent = exports.getCurrentSpanId = exports.getCurrentTraceId = exports.getCurrentSpan = exports.withSpanResult = exports.withSpan = exports.createSpan = exports.getTracer = exports.shutdownTracing = exports.getTracerProvider = exports.isTracingInitialized = exports.initTracing = exports.trackOperation = exports.instrumentAsync = exports.MetricsContext = exports.Timer = exports.ENV_KEY_SERVICE_NAME = exports.BUCKETS = exports.createGauge = exports.createHistogram = exports.createCounter = exports.startMetricsServer = exports.getMeter = exports.getSharedResource = exports.getSharedMeterProvider = exports.initMetricsProvider = void 0;
 // ====================
 // METRICS EXPORTS
 // ====================
-// Registry management
-var registry_1 = require("./metrics/registry");
-Object.defineProperty(exports, "getRegistry", { enumerable: true, get: function () { return registry_1.getRegistry; } });
-Object.defineProperty(exports, "resetRegistry", { enumerable: true, get: function () { return registry_1.resetRegistry; } });
+// Provider initialization (advanced)
+var provider_1 = require("./metrics/provider");
+Object.defineProperty(exports, "initMetricsProvider", { enumerable: true, get: function () { return provider_1.initMetricsProvider; } });
+Object.defineProperty(exports, "getSharedMeterProvider", { enumerable: true, get: function () { return provider_1.getSharedMeterProvider; } });
+Object.defineProperty(exports, "getSharedResource", { enumerable: true, get: function () { return provider_1.getSharedResource; } });
+Object.defineProperty(exports, "getMeter", { enumerable: true, get: function () { return provider_1.getMeter; } });
 // Server setup
 var server_1 = require("./metrics/server");
 Object.defineProperty(exports, "startMetricsServer", { enumerable: true, get: function () { return server_1.startMetricsServer; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;;;AAEH,uBAAuB;AACvB,kBAAkB;AAClB,uBAAuB;AAEvB,sBAAsB;AACtB,+CAAgE;AAAvD,uGAAA,WAAW,OAAA;AAAE,yGAAA,aAAa,OAAA;AAEnC,eAAe;AACf,2CAAsD;AAA7C,4GAAA,kBAAkB,OAAA;AAG3B,kBAAkB;AAClB,+CAM4B;AAL1B,yGAAA,aAAa,OAAA;AACb,2GAAA,eAAe,OAAA;AACf,uGAAA,WAAW,OAAA;AACX,mGAAA,OAAO,OAAA;AACP,gHAAA,oBAAoB,OAAA;AAItB,0BAA0B;AAC1B,6DAKmC;AAJjC,wGAAA,KAAK,OAAA;AACL,iHAAA,cAAc,OAAA;AACd,kHAAA,eAAe,OAAA;AACf,iHAAA,cAAc,OAAA;AAMhB,uBAAuB;AACvB,kBAAkB;AAClB,uBAAuB;AAEvB,2BAA2B;AAC3B,yCAKyB;AAJvB,oGAAA,WAAW,OAAA;AACX,6GAAA,oBAAoB,OAAA;AACpB,0GAAA,iBAAiB,OAAA;AACjB,wGAAA,eAAe,OAAA;AAGjB,kBAAkB;AAClB,yCAayB;AAZvB,kGAAA,SAAS,OAAA;AACT,mGAAA,UAAU,OAAA;AACV,iGAAA,QAAQ,OAAA;AACR,uGAAA,cAAc,OAAA;AACd,uGAAA,cAAc,OAAA;AACd,0GAAA,iBAAiB,OAAA;AACjB,yGAAA,gBAAgB,OAAA;AAChB,qGAAA,YAAY,OAAA;AACZ,0GAAA,iBAAiB,OAAA;AACjB,wGAAA,eAAe,OAAA;AACf,uGAAA,cAAc,OAAA;AACd,4GAAA,mBAAmB,OAAA;AAGrB,sBAAsB;AACtB,6CAU2B;AATzB,6GAAA,kBAAkB,OAAA;AAClB,8GAAA,mBAAmB,OAAA;AACnB,yGAAA,cAAc,OAAA;AACd,2GAAA,gBAAgB,OAAA;AAChB,uHAAA,4BAA4B,OAAA;AAC5B,oHAAA,yBAAyB,OAAA;AACzB,qHAAA,0BAA0B,OAAA;AAC1B,+GAAA,oBAAoB,OAAA;AACpB,oHAAA,yBAAyB,OAAA;AAK3B,0CAA8D;AAArD,qGAAA,cAAc,OAAA;AAAE,+FAAA,QAAQ,OAAA;AAyBjC,uBAAuB;AACvB,yBAAyB;AACzB,uBAAuB;AAEvB,+BAA2C;AAAlC,yGAAA,iBAAiB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;;;AAEH,uBAAuB;AACvB,kBAAkB;AAClB,uBAAuB;AAEvB,qCAAqC;AACrC,+CAK4B;AAJ1B,+GAAA,mBAAmB,OAAA;AACnB,kHAAA,sBAAsB,OAAA;AACtB,6GAAA,iBAAiB,OAAA;AACjB,oGAAA,QAAQ,OAAA;AAQV,eAAe;AACf,2CAAsD;AAA7C,4GAAA,kBAAkB,OAAA;AAG3B,kBAAkB;AAClB,+CAM4B;AAL1B,yGAAA,aAAa,OAAA;AACb,2GAAA,eAAe,OAAA;AACf,uGAAA,WAAW,OAAA;AACX,mGAAA,OAAO,OAAA;AACP,gHAAA,oBAAoB,OAAA;AAStB,0BAA0B;AAC1B,6DAKmC;AAJjC,wGAAA,KAAK,OAAA;AACL,iHAAA,cAAc,OAAA;AACd,kHAAA,eAAe,OAAA;AACf,iHAAA,cAAc,OAAA;AAGhB,uBAAuB;AACvB,kBAAkB;AAClB,uBAAuB;AAEvB,2BAA2B;AAC3B,yCAKyB;AAJvB,oGAAA,WAAW,OAAA;AACX,6GAAA,oBAAoB,OAAA;AACpB,0GAAA,iBAAiB,OAAA;AACjB,wGAAA,eAAe,OAAA;AAGjB,kBAAkB;AAClB,yCAayB;AAZvB,kGAAA,SAAS,OAAA;AACT,mGAAA,UAAU,OAAA;AACV,iGAAA,QAAQ,OAAA;AACR,uGAAA,cAAc,OAAA;AACd,uGAAA,cAAc,OAAA;AACd,0GAAA,iBAAiB,OAAA;AACjB,yGAAA,gBAAgB,OAAA;AAChB,qGAAA,YAAY,OAAA;AACZ,0GAAA,iBAAiB,OAAA;AACjB,wGAAA,eAAe,OAAA;AACf,uGAAA,cAAc,OAAA;AACd,4GAAA,mBAAmB,OAAA;AAGrB,sBAAsB;AACtB,6CAU2B;AATzB,6GAAA,kBAAkB,OAAA;AAClB,8GAAA,mBAAmB,OAAA;AACnB,yGAAA,cAAc,OAAA;AACd,2GAAA,gBAAgB,OAAA;AAChB,uHAAA,4BAA4B,OAAA;AAC5B,oHAAA,yBAAyB,OAAA;AACzB,qHAAA,0BAA0B,OAAA;AAC1B,+GAAA,oBAAoB,OAAA;AACpB,oHAAA,yBAAyB,OAAA;AAK3B,0CAA8D;AAArD,qGAAA,cAAc,OAAA;AAAE,+FAAA,QAAQ,OAAA;AAyBjC,uBAAuB;AACvB,yBAAyB;AACzB,uBAAuB;AAEvB,+BAA2C;AAAlC,yGAAA,iBAAiB,OAAA"}

package/dist/init.d.ts

@@ -2,6 +2,8 @@
  * High-level initialization helpers for observability setup.
  * Simplifies the setup of tracing, metrics, and logging for services.
  */
+import { type AutoInstrumentKey } from './metrics/provider';
+import type { Logger } from './tracing/types';
 export interface InitObservabilityConfig {
     /** Service name for telemetry */
     serviceName: string;
@@ -13,6 +15,38 @@ export interface InitObservabilityConfig {
     samplingRatio?: number;
     /** OTLP endpoint for traces (default: http://localhost:4317) */
     otlpEndpoint?: string;
+    /** Enable/disable default Node.js metrics (default: true, first call wins) */
+    enableDefaultMetrics?: boolean;
+    /**
+     * Auto-instrumentation to enable. Explicit opt-in only - no defaults.
+     *
+     * Each instrumentation requires its corresponding `@opentelemetry/instrumentation-*`
+     * package to be installed in your project. Missing packages are gracefully skipped.
+     *
+     * @example
+     * ```typescript
+     * // Express API with MongoDB
+     * autoInstrument: ['http', 'express', 'mongo']
+     *
+     * // Job with AWS SDK and MongoDB
+     * autoInstrument: ['mongo', 'aws-sdk']
+     * ```
+     */
+    autoInstrument?: AutoInstrumentKey[];
+    /**
+     * Intercept process.exit() to flush tracing data before termination.
+     * @default true
+     */
+    interceptProcessExit?: boolean;
+    /**
+     * Timeout (ms) for flushing tracing data on process.exit().
+     * @default 2000
+     */
+    exitFlushTimeoutMs?: number;
+    /**
+     * Optional logger for observability operations.
+     */
+    logger?: Logger;
 }
 export interface InitObservabilityResult {
     /** Service name used */
@@ -21,11 +55,16 @@ export interface InitObservabilityResult {
     tracingInitialized: boolean;
     /** Metrics server port */
     metricsPort: number;
+    /** Whether default metrics are currently registered (first call wins) */
+    defaultMetricsEnabled: boolean;
 }
 /**
  * Initialize observability for a service (metrics + tracing).
  * Call this once at service startup.
  *
+ * By default, this will collect Node.js runtime metrics (event loop, heap, GC, etc.)
+ * which are useful for monitoring service health even when idle.
+ *
  * @example
  * ```typescript
  * import { initObservability } from '@manifest-cyber/observability-ts';

package/dist/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,MAAM,WAAW,uBAAuB;IACtC,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,uBAAuB,CAAC,CAsClC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAuB,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAE9C,MAAM,WAAW,uBAAuB;IACtC,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;;;;;;OAcG;IACH,cAAc,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACrC;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,qBAAqB,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,uBAAuB,CAAC,CA4DlC"}

package/dist/init.js

@@ -7,10 +7,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.initObservability = initObservability;
 const setup_1 = require("./tracing/setup");
 const server_1 = require("./metrics/server");
+const provider_1 = require("./metrics/provider");
 /**
  * Initialize observability for a service (metrics + tracing).
  * Call this once at service startup.
  *
+ * By default, this will collect Node.js runtime metrics (event loop, heap, GC, etc.)
+ * which are useful for monitoring service health even when idle.
+ *
  * @example
  * ```typescript
  * import { initObservability } from '@manifest-cyber/observability-ts';
@@ -24,8 +28,17 @@ const server_1 = require("./metrics/server");
  * ```
  */
 async function initObservability(config) {
-    const { serviceName, metricsPort = 9090, tracingEnabled = process.env.OTEL_TRACING_ENABLED !== 'false', samplingRatio = getSamplingRatio(), otlpEndpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4317', } = config;
+    const { serviceName, metricsPort = 9090, tracingEnabled = process.env.OTEL_TRACING_ENABLED !== 'false', samplingRatio = getSamplingRatio(), otlpEndpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4317', enableDefaultMetrics = true, autoInstrument, interceptProcessExit = true, exitFlushTimeoutMs = 2000, logger, } = config;
     let tracingInitialized = false;
+    // Initialize OpenTelemetry metrics provider with optional auto-instrumentation
+    await (0, provider_1.initMetricsProvider)({
+        serviceName,
+        environment: process.env.ENV,
+        prometheusPort: metricsPort,
+        prometheusDisableServer: true,
+        enableRuntimeMetrics: enableDefaultMetrics,
+        autoInstrument,
+    });
     // Initialize tracing
     if (tracingEnabled) {
         await (0, setup_1.initTracing)({
@@ -41,6 +54,10 @@ async function initObservability(config) {
         });
         tracingInitialized = true;
     }
+    // Install process.exit interceptor if tracing is enabled
+    if (tracingInitialized && interceptProcessExit) {
+        installExitInterceptor(exitFlushTimeoutMs, logger);
+    }
     // Start metrics server
     await (0, server_1.startMetricsServer)({
         serviceName,
@@ -50,6 +67,8 @@ async function initObservability(config) {
         serviceName,
         tracingInitialized,
         metricsPort,
+        // Runtime metrics enabled via OpenTelemetry host-metrics/runtime-metrics packages
+        defaultMetricsEnabled: enableDefaultMetrics,
     };
 }
 /**
@@ -74,4 +93,54 @@ function getSamplingRatio() {
     // 10% sampling in production
     return 0.1;
 }
+// Symbol to mark process.exit as already intercepted
+const EXIT_INTERCEPTOR_INSTALLED = Symbol('__exitInterceptorInstalled');
+/**
+ * Intercepts process.exit() to flush tracing data before termination.
+ * This function is idempotent - calling it multiple times is safe.
+ */
+function installExitInterceptor(timeoutMs, logger) {
+    // Check if our interceptor is already installed using a symbol property
+    if (process.exit[EXIT_INTERCEPTOR_INSTALLED]) {
+        return;
+    }
+    // Capture the original process.exit only once
+    const originalExit = process.exit.bind(process);
+    let isExiting = false;
+    const interceptedExit = ((code) => {
+        if (isExiting) {
+            originalExit(code);
+            return;
+        }
+        isExiting = true;
+        logger?.info('Process exiting, flushing tracing data...', { exitCode: code });
+        const forceExitTimer = setTimeout(() => {
+            logger?.warn?.('Tracing flush timed out, forcing exit', {
+                exitCode: code,
+                timeoutMs,
+            });
+            originalExit(code);
+        }, timeoutMs);
+        void (0, setup_1.shutdownTracing)(logger)
+            .then(() => {
+            logger?.info('Tracing data flushed successfully', { exitCode: code });
+        })
+            .catch((error) => {
+            logger?.error('Error flushing tracing data', { error, exitCode: code });
+        })
+            .finally(() => {
+            clearTimeout(forceExitTimer);
+            originalExit(code);
+        });
+    });
+    // Mark the intercepted function with a non-enumerable symbol property
+    Object.defineProperty(interceptedExit, EXIT_INTERCEPTOR_INSTALLED, {
+        value: true,
+        writable: false,
+        enumerable: false,
+        configurable: false,
+    });
+    process.exit = interceptedExit;
+    logger?.info('Process.exit interceptor installed', { timeoutMs });
+}
 //# sourceMappingURL=init.js.map

package/dist/init.js.map

@@ -1 +1 @@
-{"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AA2CH,8CAwCC;AAjFD,2CAA8C;AAC9C,6CAAsD;AAwBtD;;;;;;;;;;;;;;;GAeG;AACI,KAAK,UAAU,iBAAiB,CACrC,MAA+B;IAE/B,MAAM,EACJ,WAAW,EACX,WAAW,GAAG,IAAI,EAClB,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,KAAK,OAAO,EAC7D,aAAa,GAAG,gBAAgB,EAAE,EAClC,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,2BAA2B,IAAI,uBAAuB,GAClF,GAAG,MAAM,CAAC;IAEX,IAAI,kBAAkB,GAAG,KAAK,CAAC;IAE/B,qBAAqB;IACrB,IAAI,cAAc,EAAE,CAAC;QACnB,MAAM,IAAA,mBAAW,EAAC;YAChB,WAAW;YACX,QAAQ,EAAE;gBACR,IAAI,EAAE,WAAW;gBACjB,QAAQ,EAAE,YAAY;aACvB;YACD,QAAQ,EAAE;gBACR,IAAI,EAAE,aAAa;gBACnB,aAAa,EAAE,IAAI;aACpB;SACF,CAAC,CAAC;QACH,kBAAkB,GAAG,IAAI,CAAC;IAC5B,CAAC;IAED,uBAAuB;IACvB,MAAM,IAAA,2BAAkB,EAAC;QACvB,WAAW;QACX,IAAI,EAAE,WAAW;KAClB,CAAC,CAAC;IAEH,OAAO;QACL,WAAW;QACX,kBAAkB;QAClB,WAAW;KACZ,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB;IACvB,6CAA6C;IAC7C,MAAM,gBAAgB,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;IACzD,IAAI,gBAAgB,EAAE,CAAC;QACrB,MAAM,KAAK,GAAG,UAAU,CAAC,gBAAgB,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;YAC9C,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,+BAA+B;IAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,aAAa,CAAC;IAE7C,+BAA+B;IAC/B,IAAI,GAAG,KAAK,YAAY,EAAE,CAAC;QACzB,OAAO,GAAG,CAAC;IACb,CAAC;IAED,6BAA6B;IAC7B,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"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"}

package/dist/metrics/builders.d.ts

@@ -1,4 +1,3 @@
-import { CounterConfiguration, HistogramConfiguration, GaugeConfiguration } from 'prom-client';
 /**
  * Environment variable key for service name
  * Should match the key used in @manifest-cyber/logger-ts
@@ -41,197 +40,89 @@ export declare const BUCKETS: {
     };
 };
 /**
- * Wraps a Counter to automatically inject service_name label
+ * Reset cached service name (for testing)
+ * @internal
  */
-declare class ServiceAwareCounter<T extends string> {
-    private counter;
-    private serviceName;
-    constructor(config: CounterConfiguration<T>, serviceName: string);
+export declare function resetCachedServiceName(): void;
+/**
+ * Set service name explicitly (used as fallback when environment variable is not set)
+ * @internal
+ */
+export declare function setServiceName(name: string): void;
+/**
+ * Public interface for a service-aware counter metric.
+ */
+export interface ServiceCounter<T extends string = string> {
+    /** Increment the counter */
     inc(labels?: Partial<Record<T, string | number>>, value?: number): void;
     inc(value?: number): void;
+    /** Reset the counter (no-op for OTel counters, retained for API compatibility) */
     reset(): void;
-    remove(...labelValues: string[]): void;
 }
 /**
- * Wraps a Histogram to automatically inject service_name label
+ * Public interface for a service-aware histogram metric.
  */
-declare class ServiceAwareHistogram<T extends string> {
-    private histogram;
-    private serviceName;
-    constructor(config: HistogramConfiguration<T>, serviceName: string);
+export interface ServiceHistogram<T extends string = string> {
+    /** Record an observation */
     observe(value: number): void;
     observe(labels: Partial<Record<T, string | number>>, value: number): void;
+    /** Reset the histogram (no-op for OTel histograms, retained for API compatibility) */
     reset(): void;
-    remove(...labelValues: string[]): void;
+    /** Start a timer that records duration on completion */
     startTimer(labels?: Partial<Record<T, string | number>>): (labels?: Partial<Record<T, string | number>>) => number;
-    zero(labels: Partial<Record<T, string | number>>): void;
+    /** Initialize bucket to zero (no-op for OTel, retained for API compatibility) */
+    zero(_labels: Partial<Record<T, string | number>>): void;
 }
 /**
- * Wraps a Gauge to automatically inject service_name label
+ * Public interface for a service-aware gauge metric.
  */
-declare class ServiceAwareGauge<T extends string> {
-    private gauge;
-    private serviceName;
-    constructor(config: GaugeConfiguration<T>, serviceName: string);
-    private addServiceLabel;
+export interface ServiceGauge<T extends string = string> {
+    /** Increment the gauge */
     inc(labels?: Partial<Record<T, string | number>>, value?: number): void;
     inc(value?: number): void;
+    /** Decrement the gauge */
     dec(labels?: Partial<Record<T, string | number>>, value?: number): void;
     dec(value?: number): void;
+    /** Set the gauge to a specific value */
     set(labels: Partial<Record<T, string | number>>, value: number): void;
     set(value: number): void;
+    /** Set the gauge to current Unix timestamp */
     setToCurrentTime(labels?: Partial<Record<T, string | number>>): void;
+    /** Start a timer that sets duration on completion */
     startTimer(labels?: Partial<Record<T, string | number>>): (labels?: Partial<Record<T, string | number>>) => number;
+    /** Reset the gauge */
     reset(): void;
+    /** Remove a label set */
     remove(...labelValues: string[]): void;
 }
 /**
  * Creates a counter metric
- *
- * Counters are cumulative metrics that only increase.
- * Use for counting events like requests, errors, items processed, etc.
- *
- * The metric name will be automatically suffixed with '_total' if not already present.
- * A service_name label is automatically added to all observations.
- *
- * @param config Counter configuration (name, help, labelNames)
- * @returns A new Counter instance registered with the custom registry
- *
- * @example
- * ```typescript
- * import { createCounter } from '@manifest-cyber/observability-ts';
- *
- * // Simple counter - automatically suffixed with _total
- * export const requestsTotal = createCounter({
- *   name: 'http_requests',
- *   help: 'Total number of HTTP requests',
- *   labelNames: ['method', 'status'],
- * });
- *
- * // Or provide the full name (won't duplicate suffix)
- * export const requestsTotal = createCounter({
- *   name: 'http_requests_total',
- *   help: 'Total number of HTTP requests',
- *   labelNames: ['method', 'status'],
- * });
- *
- * // Later in code (service_name is automatically added):
- * requestsTotal.inc({ method: 'GET', status: '200' });
- * // Results in: http_requests_total{service_name="my-service",method="GET",status="200"}
- * ```
  */
-export declare function createCounter(config: Omit<CounterConfiguration<string>, 'registers'>): ServiceAwareCounter<string>;
+export declare function createCounter(config: {
+    name: string;
+    help: string;
+    labelNames?: readonly string[];
+}): ServiceCounter<string>;
 /**
  * Extended histogram configuration with optional unit parameter
  */
-export interface HistogramConfig extends Omit<HistogramConfiguration<string>, 'registers'> {
-    /**
-     * Optional unit for the metric (e.g., 'bytes', 'milliseconds', 'percent')
-     * Default: 'seconds'
-     *
-     * Unit detection behavior:
-     * - If the metric name already contains a unit suffix (e.g., '_seconds', '_bytes'),
-     *   that unit will be used and this parameter is ignored (with a warning if they differ)
-     * - If no unit suffix is detected in the name, this unit will be appended
-     * - If neither name has a unit nor this parameter is provided, '_seconds' is used as default
-     *
-     * @example
-     * name: 'request_duration' → request_duration_seconds (default)
-     * name: 'file_size', unit: 'bytes' → file_size_bytes
-     * name: 'request_duration_milliseconds', unit: 'seconds' → request_duration_milliseconds (warns about conflict)
-     */
+export interface HistogramConfig {
+    name: string;
+    help: string;
+    labelNames?: readonly string[];
+    buckets?: number[];
     unit?: string;
 }
 /**
  * Creates a histogram metric
- *
- * Histograms track distributions of values, commonly used for durations.
- * They automatically track count, sum, and buckets.
- *
- * The metric name will be automatically suffixed with a unit (default: '_seconds') if not already present.
- * A service_name label is automatically added to all observations.
- *
- * **Unit detection and auto-suffixing:**
- * - If name already has a unit suffix (e.g., '_seconds', '_bytes'), it's used as-is
- * - If name lacks a unit suffix, the `unit` parameter is appended (default: 'seconds')
- * - If name has a unit AND `unit` parameter differs, a warning is logged and name's unit wins
- *
- * @param config Histogram configuration (name, help, labelNames, buckets, unit)
- * @returns A new Histogram instance registered with the custom registry
- *
- * @example
- * ```typescript
- * import { createHistogram, BUCKETS } from '@manifest-cyber/observability-ts';
- *
- * // Duration metric - automatically suffixed with _seconds (default)
- * export const requestDuration = createHistogram({
- *   name: 'http_request_duration',
- *   help: 'HTTP request duration in seconds',
- *   labelNames: ['method', 'route'],
- *   buckets: BUCKETS.DURATION.HTTP,
- * });
- * // Result: http_request_duration_seconds
- *
- * // File size metric with custom unit
- * export const fileSize = createHistogram({
- *   name: 'file_size',
- *   help: 'File size in bytes',
- *   unit: 'bytes',
- *   buckets: BUCKETS.SIZE.MEDIUM,
- * });
- * // Result: file_size_bytes
- *
- * // Provide full name (won't duplicate suffix)
- * export const fileSize2 = createHistogram({
- *   name: 'file_size_bytes',
- *   help: 'File size in bytes',
- *   buckets: BUCKETS.SIZE.MEDIUM,
- * });
- * // Result: file_size_bytes
- *
- * // Conflict scenario (logs warning, uses name's unit)
- * export const duration = createHistogram({
- *   name: 'processing_time_milliseconds',
- *   unit: 'seconds', // Warning: conflicts with _milliseconds in name
- *   buckets: BUCKETS.DURATION.FAST,
- * });
- * // Result: processing_time_milliseconds (name wins, warning logged)
- *
- * // Later in code (service_name is automatically added):
- * const duration = (Date.now() - start) / 1000;
- * requestDuration.observe({ method: 'GET', route: '/api/users' }, duration);
- * ```
  */
-export declare function createHistogram(config: HistogramConfig): ServiceAwareHistogram<string>;
+export declare function createHistogram(config: HistogramConfig): ServiceHistogram<string>;
 /**
  * Creates a gauge metric
- *
- * Gauges represent a value that can go up or down.
- * Use for measuring current state like memory usage, active connections, queue depth, etc.
- *
- * The metric name should follow Prometheus naming conventions.
- * A service_name label is automatically added to all observations.
- *
- * @param config Gauge configuration (name, help, labelNames)
- * @returns A new Gauge instance registered with the custom registry
- *
- * @example
- * ```typescript
- * import { createGauge } from '@manifest-cyber/observability-ts';
- *
- * // Simple gauge metric
- * export const activeConnections = createGauge({
- *   name: 'active_connections',
- *   help: 'Number of active connections',
- *   labelNames: ['type'],
- * });
- *
- * // Later in code (service_name is automatically added):
- * activeConnections.inc({ type: 'websocket' });  // increment
- * activeConnections.dec({ type: 'websocket' });  // decrement
- * activeConnections.set({ type: 'http' }, 42);   // set to specific value
- * ```
  */
-export declare function createGauge(config: Omit<GaugeConfiguration<string>, 'registers'>): ServiceAwareGauge<string>;
-export {};
+export declare function createGauge(config: {
+    name: string;
+    help: string;
+    labelNames?: readonly string[];
+}): ServiceGauge<string>;
 //# sourceMappingURL=builders.d.ts.map

package/dist/metrics/builders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/metrics/builders.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/metrics/builders.ts"],"names":[],"mappings":"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"}