@breadstone/archipel-platform-telemetry 0.0.19 → 0.0.21

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.19",
+  "version": "0.0.21",
   "description": "OpenTelemetry integration with tracing, metrics, and graceful no-op fallback for NestJS.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -28,8 +28,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@breadstone/archipel-platform-caching": "0.0.19",
-    "@breadstone/archipel-platform-core": "0.0.19",
+    "@breadstone/archipel-platform-caching": "0.0.21",
+    "@breadstone/archipel-platform-core": "0.0.21",
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/exporter-metrics-otlp-http": "0.215.0",
     "@opentelemetry/exporter-trace-otlp-http": "0.215.0",

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/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) {