@breadstone/archipel-platform-telemetry 0.0.20 → 0.0.22

package/README.md

@@ -20,6 +20,9 @@ import { TelemetryModule } from '@breadstone/archipel-platform-telemetry';
 - **Graceful degradation**: Falls back to `NoopTelemetryFacade` when disabled — zero overhead
 - **Health checks**: Integration with health module for observability readiness
 - **Structured logging**: `TelemetryLoggerService` with request correlation IDs
+- **Eager metric init**: `MetricsService` creates instruments at startup via `OnModuleInit`
+- **Write-once SDK guard**: `OtelSdkHolder` prevents accidental double-initialization of the OpenTelemetry SDK
+- **Shutdown timeout**: SDK shutdown is capped at 5 seconds to prevent hanging processes
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breadstone/archipel-platform-telemetry",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "description": "OpenTelemetry integration with tracing, metrics, and graceful no-op fallback for NestJS.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -28,26 +28,60 @@
     "README.md"
   ],
   "dependencies": {
-    "@breadstone/archipel-platform-caching": "0.0.20",
-    "@breadstone/archipel-platform-core": "0.0.20",
-    "@opentelemetry/api": "1.9.1",
-    "@opentelemetry/exporter-metrics-otlp-http": "0.215.0",
-    "@opentelemetry/exporter-trace-otlp-http": "0.215.0",
-    "@opentelemetry/instrumentation-express": "0.63.0",
-    "@opentelemetry/instrumentation-http": "0.215.0",
-    "@opentelemetry/resources": "2.7.0",
-    "@opentelemetry/sdk-node": "0.215.0",
-    "@opentelemetry/semantic-conventions": "1.40.0",
+    "@breadstone/archipel-platform-caching": "0.0.22",
+    "@breadstone/archipel-platform-core": "0.0.22",
     "tslib": "2.8.1"
   },
   "peerDependencies": {
     "@nestjs/common": ">=11.0.0",
     "@nestjs/core": ">=11.0.0",
+    "@opentelemetry/api": ">=1.9.0",
+    "@opentelemetry/exporter-metrics-otlp-http": ">=0.200.0",
+    "@opentelemetry/exporter-trace-otlp-http": ">=0.200.0",
+    "@opentelemetry/instrumentation-express": ">=0.60.0",
+    "@opentelemetry/instrumentation-http": ">=0.200.0",
+    "@opentelemetry/resources": ">=2.0.0",
+    "@opentelemetry/sdk-node": ">=0.200.0",
+    "@opentelemetry/semantic-conventions": ">=1.30.0",
     "rxjs": ">=7.0.0"
   },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-metrics-otlp-http": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-trace-otlp-http": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation-express": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation-http": {
+      "optional": true
+    },
+    "@opentelemetry/resources": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-node": {
+      "optional": true
+    },
+    "@opentelemetry/semantic-conventions": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@nestjs/common": "11.1.19",
     "@nestjs/core": "11.1.19",
+    "@opentelemetry/api": "1.9.1",
+    "@opentelemetry/exporter-metrics-otlp-http": "0.215.0",
+    "@opentelemetry/exporter-trace-otlp-http": "0.215.0",
+    "@opentelemetry/instrumentation-express": "0.63.0",
+    "@opentelemetry/instrumentation-http": "0.215.0",
+    "@opentelemetry/resources": "2.7.0",
+    "@opentelemetry/sdk-node": "0.215.0",
+    "@opentelemetry/semantic-conventions": "1.40.0",
     "rxjs": "7.8.2",
     "vitest": "4.1.4"
   }

package/src/OtelSdkHolder.d.ts

@@ -12,6 +12,7 @@ export declare class OtelSdkHolder implements OnApplicationShutdown {
     private _sdk?;
     /**
      * Stores the SDK reference so it can be shut down later.
+     * Can only be called once — subsequent calls are ignored.
      */
     setSdk(sdk: unknown): void;
     /** @inheritdoc */

package/src/OtelSdkHolder.js

@@ -24,8 +24,13 @@ let OtelSdkHolder = OtelSdkHolder_1 = class OtelSdkHolder {
     // #region Methods
     /**
      * Stores the SDK reference so it can be shut down later.
+     * Can only be called once — subsequent calls are ignored.
      */
     setSdk(sdk) {
+        if (this._sdk) {
+            this._logger.warn('OtelSdkHolder.setSdk() called more than once — ignoring.');
+            return;
+        }
         this._sdk = sdk;
     }
     /** @inheritdoc */
@@ -34,7 +39,7 @@ let OtelSdkHolder = OtelSdkHolder_1 = class OtelSdkHolder {
             return;
         }
         try {
-            await this._sdk.shutdown();
+            await Promise.race([this._sdk.shutdown(), new Promise((resolve) => setTimeout(resolve, 5_000))]);
             this._logger.log('OpenTelemetry SDK shut down successfully.');
         }
         catch (error) {

package/src/TelemetryModule.js

@@ -14,14 +14,14 @@ const MetricsService_1 = require("./metrics/MetricsService");
 const TelemetryOptions_1 = require("./options/TelemetryOptions");
 const OtelSdkHolder_1 = require("./OtelSdkHolder");
 const TelemetryRuleEngine_1 = require("./rules/TelemetryRuleEngine");
-const tokens_1 = require("./tokens");
+const TelemetryTokens_1 = require("./tokens/TelemetryTokens");
 let TelemetryModule = TelemetryModule_1 = class TelemetryModule {
     static register(options) {
         return {
             module: TelemetryModule_1,
             providers: [
                 {
-                    provide: tokens_1.TELEMETRY_OPTIONS,
+                    provide: TelemetryTokens_1.TELEMETRY_OPTIONS,
                     useFactory: () => {
                         const merged = {
                             ...TelemetryOptions_1.defaultTelemetryOptions,
@@ -32,21 +32,21 @@ let TelemetryModule = TelemetryModule_1 = class TelemetryModule {
                     },
                 },
                 {
-                    provide: tokens_1.TELEMETRY_ENABLED,
-                    inject: [tokens_1.TELEMETRY_OPTIONS],
+                    provide: TelemetryTokens_1.TELEMETRY_ENABLED,
+                    inject: [TelemetryTokens_1.TELEMETRY_OPTIONS],
                     useFactory: (cfg) => cfg.enabled,
                 },
                 {
                     provide: TelemetryRuleEngine_1.TelemetryRuleEngine,
-                    inject: [tokens_1.TELEMETRY_OPTIONS, MetricsService_1.MetricsService],
+                    inject: [TelemetryTokens_1.TELEMETRY_OPTIONS, MetricsService_1.MetricsService],
                     useFactory: (cfg, metricsService) => new TelemetryRuleEngine_1.TelemetryRuleEngine(cfg, metricsService),
                 },
                 TelemetryLoggerService_1.TelemetryLoggerService,
                 OtelSdkHolder_1.OtelSdkHolder,
                 MetricsService_1.MetricsService,
                 {
-                    provide: tokens_1.TELEMETRY_FACADE,
-                    inject: [tokens_1.TELEMETRY_OPTIONS, tokens_1.TELEMETRY_ENABLED, OtelSdkHolder_1.OtelSdkHolder],
+                    provide: TelemetryTokens_1.TELEMETRY_FACADE,
+                    inject: [TelemetryTokens_1.TELEMETRY_OPTIONS, TelemetryTokens_1.TELEMETRY_ENABLED, OtelSdkHolder_1.OtelSdkHolder],
                     useFactory: async (cfg, enabled, sdkHolder) => {
                         if (!enabled)
                             return new NoopTelemetryFacade_1.NoopTelemetryFacade();
@@ -63,13 +63,13 @@ let TelemetryModule = TelemetryModule_1 = class TelemetryModule {
                 },
                 {
                     provide: core_1.APP_INTERCEPTOR,
-                    inject: [tokens_1.TELEMETRY_FACADE, tokens_1.TELEMETRY_OPTIONS],
+                    inject: [TelemetryTokens_1.TELEMETRY_FACADE, TelemetryTokens_1.TELEMETRY_OPTIONS],
                     useFactory: (facade, cfg) => cfg.interceptor?.operation
                         ? new OperationTelemetryInterceptor_1.OperationTelemetryInterceptor(facade)
                         : { intercept: (_, next) => next.handle() },
                 },
             ],
-            exports: [tokens_1.TELEMETRY_FACADE, MetricsService_1.MetricsService],
+            exports: [TelemetryTokens_1.TELEMETRY_FACADE, MetricsService_1.MetricsService],
         };
     }
 };

package/src/core/TelemetryCacheMetricsRecorder.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TelemetryCacheMetricsRecorder = void 0;
 const tslib_1 = require("tslib");
 const common_1 = require("@nestjs/common");
-const tokens_1 = require("../tokens");
+const TelemetryTokens_1 = require("../tokens/TelemetryTokens");
 // #endregion
 /**
  * Generic cache metrics recorder that forwards cache lifecycle events
@@ -56,7 +56,7 @@ let TelemetryCacheMetricsRecorder = class TelemetryCacheMetricsRecorder {
 exports.TelemetryCacheMetricsRecorder = TelemetryCacheMetricsRecorder;
 exports.TelemetryCacheMetricsRecorder = TelemetryCacheMetricsRecorder = tslib_1.__decorate([
     (0, common_1.Injectable)(),
-    tslib_1.__param(0, (0, common_1.Inject)(tokens_1.TELEMETRY_FACADE)),
+    tslib_1.__param(0, (0, common_1.Inject)(TelemetryTokens_1.TELEMETRY_FACADE)),
     tslib_1.__metadata("design:paramtypes", [Object])
 ], TelemetryCacheMetricsRecorder);
 //# sourceMappingURL=TelemetryCacheMetricsRecorder.js.map

package/src/index.d.ts

@@ -7,4 +7,4 @@ export * from './options/TelemetryOptions';
 export { OtelSdkHolder } from './OtelSdkHolder';
 export * from './rules/TelemetryRuleEngine';
 export { TelemetryModule } from './TelemetryModule';
-export * from './tokens';
+export * from './tokens/TelemetryTokens';

package/src/index.js

@@ -13,5 +13,5 @@ Object.defineProperty(exports, "OtelSdkHolder", { enumerable: true, get: functio
 tslib_1.__exportStar(require("./rules/TelemetryRuleEngine"), exports);
 var TelemetryModule_1 = require("./TelemetryModule");
 Object.defineProperty(exports, "TelemetryModule", { enumerable: true, get: function () { return TelemetryModule_1.TelemetryModule; } });
-tslib_1.__exportStar(require("./tokens"), exports);
+tslib_1.__exportStar(require("./tokens/TelemetryTokens"), exports);
 //# sourceMappingURL=index.js.map

package/src/logger/TelemetryLoggerService.js

@@ -7,18 +7,40 @@ const TelemetryRuleEngine_1 = require("../rules/TelemetryRuleEngine");
 let TelemetryLoggerService = class TelemetryLoggerService extends common_1.ConsoleLogger {
     // #endregion
     // #region Ctor
-    constructor(ruleEngine) { super(); this._ruleEngine = ruleEngine; }
+    constructor(ruleEngine) {
+        super();
+        this._ruleEngine = ruleEngine;
+    }
     // #endregion
     // #region Methods
-    log(message, context) { this.forward(message); super.log(message, context); }
-    error(message, stack, context) { this.forward(message); super.error(message, stack, context); }
-    warn(message, context) { this.forward(message); super.warn(message, context); }
-    debug(message, context) { this.forward(message); super.debug?.(message, context); }
-    verbose(message, context) { this.forward(message); super.verbose?.(message, context); }
-    forward(message) { try {
-        this._ruleEngine?.process(message);
+    log(message, context) {
+        this.forward(message);
+        super.log(message, context);
+    }
+    error(message, stack, context) {
+        this.forward(message);
+        super.error(message, stack, context);
+    }
+    warn(message, context) {
+        this.forward(message);
+        super.warn(message, context);
+    }
+    debug(message, context) {
+        this.forward(message);
+        super.debug?.(message, context);
+    }
+    verbose(message, context) {
+        this.forward(message);
+        super.verbose?.(message, context);
+    }
+    forward(message) {
+        try {
+            this._ruleEngine?.process(message);
+        }
+        catch (error) {
+            super.warn?.(`TelemetryRuleEngine.process failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
     }
-    catch { /* noop */ } }
 };
 exports.TelemetryLoggerService = TelemetryLoggerService;
 exports.TelemetryLoggerService = TelemetryLoggerService = tslib_1.__decorate([

package/src/metrics/MetricsService.d.ts

@@ -1,20 +1,27 @@
+import { type OnModuleInit } from '@nestjs/common';
 export interface IMetricInstruments {
     cacheCounter?: unknown;
     opCounter?: unknown;
     opDuration?: unknown;
 }
 /**
- * Provides lazily-initialized OpenTelemetry metric instruments.
+ * Provides eagerly-initialized OpenTelemetry metric instruments.
  *
  * Replaces the former module-level `let instruments` closure (TEL-4).
  *
  * @public
  */
-export declare class MetricsService {
+export declare class MetricsService implements OnModuleInit {
     private readonly _logger;
     private _instruments?;
     /**
-     * Returns the cached metric instruments, creating them on first access.
+     * Eagerly initializes metric instruments at module startup.
+     *
+     * @public
+     */
+    onModuleInit(): void;
+    /**
+     * Returns the cached metric instruments.
      */
     getInstruments(): IMetricInstruments | undefined;
 }

package/src/metrics/MetricsService.js

@@ -7,7 +7,7 @@ const tslib_1 = require("tslib");
 const common_1 = require("@nestjs/common");
 // #endregion
 /**
- * Provides lazily-initialized OpenTelemetry metric instruments.
+ * Provides eagerly-initialized OpenTelemetry metric instruments.
  *
  * Replaces the former module-level `let instruments` closure (TEL-4).
  *
@@ -22,11 +22,13 @@ let MetricsService = MetricsService_1 = class MetricsService {
     // #endregion
     // #region Methods
     /**
-     * Returns the cached metric instruments, creating them on first access.
+     * Eagerly initializes metric instruments at module startup.
+     *
+     * @public
      */
-    getInstruments() {
+    onModuleInit() {
         if (this._instruments) {
-            return this._instruments;
+            return;
         }
         try {
             const api = require('@opentelemetry/api');
@@ -36,13 +38,17 @@ let MetricsService = MetricsService_1 = class MetricsService {
                 opCounter: meter.createCounter('operation_event_total', { description: 'Operation success/error events' }),
                 opDuration: meter.createHistogram('operation_duration_ms', { description: 'Operation durations ms' }),
             };
-            return this._instruments;
         }
         catch (error) {
             this._logger.warn('Failed to initialize metric instruments.', error.message);
-            return undefined;
         }
     }
+    /**
+     * Returns the cached metric instruments.
+     */
+    getInstruments() {
+        return this._instruments;
+    }
 };
 exports.MetricsService = MetricsService;
 exports.MetricsService = MetricsService = MetricsService_1 = tslib_1.__decorate([

package/src/rules/TelemetryRuleEngine.d.ts

@@ -3,6 +3,7 @@ import { ITelemetryOptions } from '../options/TelemetryOptions';
 export declare class TelemetryRuleEngine {
     private readonly _options;
     private readonly _metricsService;
+    private readonly _logger;
     constructor(options: ITelemetryOptions, metricsService: MetricsService);
     process(message: string): void;
     private handleCache;

package/src/rules/TelemetryRuleEngine.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TelemetryRuleEngine = void 0;
+const common_1 = require("@nestjs/common");
 class TelemetryRuleEngine {
     // #endregion
     // #region Ctor
     constructor(options, metricsService) {
+        this._logger = new common_1.Logger(TelemetryRuleEngine.name);
         this._options = options;
         this._metricsService = metricsService;
     }
@@ -37,8 +39,8 @@ class TelemetryRuleEngine {
                 phase: tokens['phase'] ?? 'none',
             });
         }
-        catch {
-            /* noop */
+        catch (error) {
+            this._logger.warn('Cache metric recording failed', { error });
         }
     }
     handleOperation(line) {
@@ -58,16 +60,16 @@ class TelemetryRuleEngine {
         try {
             counter?.add(1, labels);
         }
-        catch {
-            /* noop */
+        catch (error) {
+            this._logger.warn('Operation counter recording failed', { error });
         }
         const dur = tokens['duration_ms'] ? Number(tokens['duration_ms']) : undefined;
         if (dur !== undefined && !Number.isNaN(dur)) {
             try {
                 histogram?.record(dur, labels);
             }
-            catch {
-                /* noop */
+            catch (error) {
+                this._logger.warn('Operation histogram recording failed', { error });
             }
         }
     }
@@ -93,8 +95,8 @@ class TelemetryRuleEngine {
                 histogram?.record(valueRaw, baseLabels);
             }
         }
-        catch {
-            /* noop */
+        catch (error) {
+            this._logger.warn('Client metric recording failed', { error });
         }
     }
     parseTokens(line) {

package/src/{tokens.js → tokens/TelemetryTokens.js}

@@ -5,4 +5,4 @@ exports.TELEMETRY_ENABLED = exports.TELEMETRY_FACADE = exports.TELEMETRY_OPTIONS
 exports.TELEMETRY_OPTIONS = Symbol('TELEMETRY_OPTIONS');
 exports.TELEMETRY_FACADE = Symbol('TELEMETRY_FACADE');
 exports.TELEMETRY_ENABLED = Symbol('TELEMETRY_ENABLED');
-//# sourceMappingURL=tokens.js.map
+//# sourceMappingURL=TelemetryTokens.js.map