@breadstone/archipel-platform-telemetry 0.0.24 → 0.0.25

package/README.md

@@ -8,7 +8,7 @@ Application monitoring, metrics, and distributed tracing infrastructure for Nest
 - **Distributed tracing** — OpenTelemetry SDK integration with automatic span creation
 - **Operation interceptor** — `OperationTelemetryInterceptor` wraps controller methods in telemetry operations
 - **Graceful degradation** — Falls back to `NoopTelemetryFacade` when disabled — zero overhead
-- **Health checks** — Integration with health module for observability readiness
+- **Health checks** — `TelemetryHealthIndicator` for readiness probes (separate `/health` subpath)
 - **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
@@ -19,6 +19,9 @@ Application monitoring, metrics, and distributed tracing infrastructure for Nest
 ```typescript
 import { TelemetryModule } from '@breadstone/archipel-platform-telemetry';
 
+// Health indicator (optional)
+import { TelemetryHealthIndicator } from '@breadstone/archipel-platform-telemetry/health';
+
 @Module({
   imports: [TelemetryModule],
 })
@@ -32,15 +35,17 @@ export class AppModule {}
 
 ## Peer Dependencies
 
-| Package                                     | Required | Notes             |
-| ------------------------------------------- | -------- | ----------------- |
-| `@nestjs/common`                            | Yes      | NestJS core       |
-| `@nestjs/core`                              | Yes      | NestJS core       |
-| `@opentelemetry/api`                        | Yes      | OpenTelemetry API |
-| `@opentelemetry/sdk-node`                   | Yes      | OpenTelemetry SDK |
-| `@opentelemetry/exporter-metrics-otlp-http` | Yes      | Metrics exporter  |
-| `@opentelemetry/exporter-trace-otlp-http`   | Yes      | Trace exporter    |
-| `rxjs`                                      | Yes      | Reactive streams  |
+| Package                                     | Required | Notes                         |
+| ------------------------------------------- | -------- | ----------------------------- |
+| `@nestjs/common`                            | Yes      | NestJS core                   |
+| `@nestjs/core`                              | Yes      | NestJS core                   |
+| `@opentelemetry/api`                        | Yes      | OpenTelemetry API             |
+| `@opentelemetry/sdk-node`                   | Yes      | OpenTelemetry SDK             |
+| `@opentelemetry/exporter-metrics-otlp-http` | Yes      | Metrics exporter              |
+| `@opentelemetry/exporter-trace-otlp-http`   | Yes      | Trace exporter                |
+| `rxjs`                                      | Yes      | Reactive streams              |
+| `@breadstone/archipel-platform-health`      | No       | Required for health indicator |
+| `@nestjs/terminus`                          | No       | Required for health indicator |
 
 ## Documentation
 

package/package.json

@@ -1,10 +1,27 @@
 {
   "name": "@breadstone/archipel-platform-telemetry",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "description": "OpenTelemetry integration with tracing, metrics, and graceful no-op fallback for NestJS.",
   "type": "commonjs",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "health": [
+        "./src/health/index.d.ts"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./health": {
+      "types": "./src/health/index.d.ts",
+      "default": "./src/health/index.js"
+    }
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -28,13 +45,15 @@
     "README.md"
   ],
   "dependencies": {
-    "@breadstone/archipel-platform-caching": "0.0.24",
-    "@breadstone/archipel-platform-core": "0.0.24",
+    "@breadstone/archipel-platform-caching": "0.0.25",
+    "@breadstone/archipel-platform-core": "0.0.25",
     "tslib": "2.8.1"
   },
   "peerDependencies": {
+    "@breadstone/archipel-platform-health": ">=0.0.1",
     "@nestjs/common": ">=11.0.0",
     "@nestjs/core": ">=11.0.0",
+    "@nestjs/terminus": ">=11.0.0",
     "@opentelemetry/api": ">=1.9.0",
     "@opentelemetry/exporter-metrics-otlp-http": ">=0.200.0",
     "@opentelemetry/exporter-trace-otlp-http": ">=0.200.0",
@@ -46,6 +65,12 @@
     "rxjs": ">=7.0.0"
   },
   "peerDependenciesMeta": {
+    "@breadstone/archipel-platform-health": {
+      "optional": true
+    },
+    "@nestjs/terminus": {
+      "optional": true
+    },
     "@opentelemetry/api": {
       "optional": true
     },

package/src/OtelSdkHolder.d.ts

@@ -10,6 +10,12 @@ import { OnApplicationShutdown } from '@nestjs/common';
 export declare class OtelSdkHolder implements OnApplicationShutdown {
     private readonly _logger;
     private _sdk?;
+    /**
+     * Whether the OpenTelemetry SDK has been initialized.
+     *
+     * @public
+     */
+    get isInitialized(): boolean;
     /**
      * Stores the SDK reference so it can be shut down later.
      * Can only be called once - subsequent calls are ignored.

package/src/OtelSdkHolder.js

@@ -21,6 +21,16 @@ let OtelSdkHolder = OtelSdkHolder_1 = class OtelSdkHolder {
         // #endregion
     }
     // #endregion
+    // #region Properties
+    /**
+     * Whether the OpenTelemetry SDK has been initialized.
+     *
+     * @public
+     */
+    get isInitialized() {
+        return this._sdk !== undefined;
+    }
+    // #endregion
     // #region Methods
     /**
      * Stores the SDK reference so it can be shut down later.

package/src/health/TelemetryHealthIndicator.d.ts

@@ -0,0 +1,22 @@
+import { IHealthIndicator } from '@breadstone/archipel-platform-health';
+import { HealthIndicatorResult } from '@nestjs/terminus';
+import { OtelSdkHolder } from '../OtelSdkHolder';
+/**
+ * Health indicator for the telemetry infrastructure.
+ * Checks whether the OpenTelemetry SDK has been initialized via {@link OtelSdkHolder}.
+ *
+ * @public
+ */
+export declare class TelemetryHealthIndicator implements IHealthIndicator {
+    private readonly _sdkHolder?;
+    constructor(sdkHolder?: OtelSdkHolder);
+    readonly key: string;
+    /**
+     * Checks whether the OpenTelemetry SDK has been initialized.
+     * Returns disabled status when no SDK holder is configured.
+     *
+     * @public
+     * @returns The health indicator result.
+     */
+    check(): HealthIndicatorResult<string>;
+}

package/src/health/TelemetryHealthIndicator.js

@@ -0,0 +1,56 @@
+"use strict";
+// #region Imports
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelemetryHealthIndicator = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const OtelSdkHolder_1 = require("../OtelSdkHolder");
+// #endregion
+/**
+ * Health indicator for the telemetry infrastructure.
+ * Checks whether the OpenTelemetry SDK has been initialized via {@link OtelSdkHolder}.
+ *
+ * @public
+ */
+let TelemetryHealthIndicator = class TelemetryHealthIndicator {
+    // #endregion
+    // #region Ctor
+    constructor(sdkHolder) {
+        // #endregion
+        // #region Properties
+        this.key = 'telemetry';
+        this._sdkHolder = sdkHolder;
+    }
+    // #endregion
+    // #region Methods
+    /**
+     * Checks whether the OpenTelemetry SDK has been initialized.
+     * Returns disabled status when no SDK holder is configured.
+     *
+     * @public
+     * @returns The health indicator result.
+     */
+    check() {
+        if (!this._sdkHolder) {
+            return {
+                telemetry: {
+                    status: 'up',
+                    disabled: true,
+                },
+            };
+        }
+        return {
+            telemetry: {
+                status: this._sdkHolder.isInitialized ? 'up' : 'down',
+                sdkInitialized: this._sdkHolder.isInitialized,
+            },
+        };
+    }
+};
+exports.TelemetryHealthIndicator = TelemetryHealthIndicator;
+exports.TelemetryHealthIndicator = TelemetryHealthIndicator = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(0, (0, common_1.Optional)()),
+    tslib_1.__metadata("design:paramtypes", [OtelSdkHolder_1.OtelSdkHolder])
+], TelemetryHealthIndicator);
+//# sourceMappingURL=TelemetryHealthIndicator.js.map

package/src/health/index.d.ts

@@ -0,0 +1 @@
+export { TelemetryHealthIndicator } from './TelemetryHealthIndicator';

package/src/health/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelemetryHealthIndicator = void 0;
+var TelemetryHealthIndicator_1 = require("./TelemetryHealthIndicator");
+Object.defineProperty(exports, "TelemetryHealthIndicator", { enumerable: true, get: function () { return TelemetryHealthIndicator_1.TelemetryHealthIndicator; } });
+//# sourceMappingURL=index.js.map