@breadstone/archipel-platform-telemetry 0.0.23 → 0.0.25

package/README.md

@@ -1,28 +1,55 @@
 # @breadstone/archipel-platform-telemetry
 
-Application monitoring, metrics, and telemetry infrastructure.
+Application monitoring, metrics, and distributed tracing infrastructure for NestJS.
+
+## Features
+
+- **Metrics collection** — Counter, histogram, and gauge recording via `TelemetryFacade`
+- **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** — `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
+- **Shutdown timeout** — SDK shutdown is capped at 5 seconds to prevent hanging processes
 
 ## Quick Start
 
 ```typescript
 import { TelemetryModule } from '@breadstone/archipel-platform-telemetry';
+
+// Health indicator (optional)
+import { TelemetryHealthIndicator } from '@breadstone/archipel-platform-telemetry/health';
+
+@Module({
+  imports: [TelemetryModule],
+})
+export class AppModule {}
 ```
 
-## Documentation
+## Lifecycle
 
-📖 **Telemetry Guide:** [`.docs/guides/telemetry-and-observability.md`](../../.docs/guides/telemetry-and-observability.md)
+- **Startup (`OnModuleInit`):** `MetricsService` creates metric instruments eagerly.
+- **Shutdown:** SDK shutdown is capped at 5 seconds to prevent hanging processes.
 
-## Features
+## 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              |
+| `@breadstone/archipel-platform-health`      | No       | Required for health indicator |
+| `@nestjs/terminus`                          | No       | Required for health indicator |
 
-- **Metrics collection**: Counter, histogram, and gauge recording via `TelemetryFacade`
-- **Distributed tracing**: OpenTelemetry SDK integration with automatic span creation
-- **Operation interceptor**: `OperationTelemetryInterceptor` wraps controller methods in telemetry operations (returns `Observable<unknown>`)
-- **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
+## Documentation
+
+📖 **Telemetry Guide:** [`.docs/guides/telemetry-and-observability.md`](../../.docs/guides/telemetry-and-observability.md)
 
 ## Development
 

package/package.json

@@ -1,10 +1,27 @@
 {
   "name": "@breadstone/archipel-platform-telemetry",
-  "version": "0.0.23",
+  "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.23",
-    "@breadstone/archipel-platform-core": "0.0.23",
+    "@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