@breadstone/archipel-mcp 0.0.15 → 0.0.16

package/data/packages/platform-telemetry/api/Interface.ITelemetryOptions.md

@@ -0,0 +1,136 @@
+---
+title: 'Interface: ITelemetryOptions'
+generated: true
+editUrl: false
+---
+# Interface: ITelemetryOptions
+
+Defined in: [options/TelemetryOptions.ts:15](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/options/TelemetryOptions.ts#L15)
+
+## Properties
+
+### enabled
+
+```ts
+enabled: boolean;
+```
+
+Defined in: [options/TelemetryOptions.ts:16](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/options/TelemetryOptions.ts#L16)
+
+***
+
+### environment?
+
+```ts
+optional environment?: string;
+```
+
+Defined in: [options/TelemetryOptions.ts:18](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/options/TelemetryOptions.ts#L18)
+
+***
+
+### instrumentation?
+
+```ts
+optional instrumentation?: {
+  express?: boolean;
+  http?: boolean;
+};
+```
+
+Defined in: [options/TelemetryOptions.ts:22](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/options/TelemetryOptions.ts#L22)
+
+#### express?
+
+```ts
+optional express?: boolean;
+```
+
+#### http?
+
+```ts
+optional http?: boolean;
+```
+
+***
+
+### interceptor?
+
+```ts
+optional interceptor?: {
+  operation?: boolean;
+};
+```
+
+Defined in: [options/TelemetryOptions.ts:30](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/options/TelemetryOptions.ts#L30)
+
+#### operation?
+
+```ts
+optional operation?: boolean;
+```
+
+***
+
+### logCorrelation?
+
+```ts
+optional logCorrelation?: boolean;
+```
+
+Defined in: [options/TelemetryOptions.ts:21](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/options/TelemetryOptions.ts#L21)
+
+***
+
+### metrics?
+
+```ts
+optional metrics?: ITelemetryMetricsOptions;
+```
+
+Defined in: [options/TelemetryOptions.ts:20](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/options/TelemetryOptions.ts#L20)
+
+***
+
+### pattern?
+
+```ts
+optional pattern?: {
+  enableCacheMetrics?: boolean;
+  enableOperationMetrics?: boolean;
+};
+```
+
+Defined in: [options/TelemetryOptions.ts:26](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/options/TelemetryOptions.ts#L26)
+
+#### enableCacheMetrics?
+
+```ts
+optional enableCacheMetrics?: boolean;
+```
+
+#### enableOperationMetrics?
+
+```ts
+optional enableOperationMetrics?: boolean;
+```
+
+***
+
+### serviceName
+
+```ts
+serviceName: string;
+```
+
+Defined in: [options/TelemetryOptions.ts:17](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/options/TelemetryOptions.ts#L17)
+
+***
+
+### traces?
+
+```ts
+optional traces?: ITelemetryTracesOptions;
+```
+
+Defined in: [options/TelemetryOptions.ts:19](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/options/TelemetryOptions.ts#L19)

package/data/packages/platform-telemetry/api/Interface.ITelemetryTracesOptions.md

@@ -0,0 +1,38 @@
+---
+title: 'Interface: ITelemetryTracesOptions'
+generated: true
+editUrl: false
+---
+# Interface: ITelemetryTracesOptions
+
+Defined in: [options/TelemetryOptions.ts:3](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/options/TelemetryOptions.ts#L3)
+
+## Properties
+
+### enabled
+
+```ts
+enabled: boolean;
+```
+
+Defined in: [options/TelemetryOptions.ts:4](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/options/TelemetryOptions.ts#L4)
+
+***
+
+### exporter?
+
+```ts
+optional exporter?: "otlp-http" | "console";
+```
+
+Defined in: [options/TelemetryOptions.ts:6](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/options/TelemetryOptions.ts#L6)
+
+***
+
+### samplingRatio?
+
+```ts
+optional samplingRatio?: number;
+```
+
+Defined in: [options/TelemetryOptions.ts:5](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/options/TelemetryOptions.ts#L5)

package/data/packages/platform-telemetry/api/Variable.TELEMETRY_ENABLED.md

@@ -0,0 +1,12 @@
+---
+title: 'Variable: TELEMETRY\_ENABLED'
+generated: true
+editUrl: false
+---
+# Variable: TELEMETRY\_ENABLED
+
+```ts
+const TELEMETRY_ENABLED: typeof TELEMETRY_ENABLED;
+```
+
+Defined in: [tokens.ts:4](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/tokens.ts#L4)

package/data/packages/platform-telemetry/api/Variable.TELEMETRY_FACADE.md

@@ -0,0 +1,12 @@
+---
+title: 'Variable: TELEMETRY\_FACADE'
+generated: true
+editUrl: false
+---
+# Variable: TELEMETRY\_FACADE
+
+```ts
+const TELEMETRY_FACADE: typeof TELEMETRY_FACADE;
+```
+
+Defined in: [tokens.ts:3](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/tokens.ts#L3)

package/data/packages/platform-telemetry/api/Variable.TELEMETRY_OPTIONS.md

@@ -0,0 +1,12 @@
+---
+title: 'Variable: TELEMETRY\_OPTIONS'
+generated: true
+editUrl: false
+---
+# Variable: TELEMETRY\_OPTIONS
+
+```ts
+const TELEMETRY_OPTIONS: typeof TELEMETRY_OPTIONS;
+```
+
+Defined in: [tokens.ts:2](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/tokens.ts#L2)

package/data/packages/platform-telemetry/api/Variable.defaultTelemetryOptions.md

@@ -0,0 +1,12 @@
+---
+title: 'Variable: defaultTelemetryOptions'
+generated: true
+editUrl: false
+---
+# Variable: defaultTelemetryOptions
+
+```ts
+const defaultTelemetryOptions: ITelemetryOptions;
+```
+
+Defined in: [options/TelemetryOptions.ts:35](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/options/TelemetryOptions.ts#L35)

package/data/packages/platform-telemetry/api/index.md

@@ -0,0 +1,44 @@
+---
+title: '@breadstone/archipel-platform-telemetry'
+generated: true
+editUrl: false
+---
+# @breadstone/archipel-platform-telemetry
+
+## Classes
+
+| Class | Description |
+| ------ | ------ |
+| [MetricsService](Class.MetricsService) | Provides lazily-initialized OpenTelemetry metric instruments. |
+| [NoopTelemetryFacade](Class.NoopTelemetryFacade) | - |
+| [OtelSdkHolder](Class.OtelSdkHolder) | Holds a reference to the OpenTelemetry NodeSDK instance and performs a graceful shutdown when the application terminates. |
+| [TelemetryCacheMetricsRecorder](Class.TelemetryCacheMetricsRecorder) | Generic cache metrics recorder that forwards cache lifecycle events into the telemetry facade (which may be a noop when disabled). |
+| [TelemetryFacade](Class.TelemetryFacade) | - |
+| [TelemetryLoggerService](Class.TelemetryLoggerService) | - |
+| [TelemetryModule](Class.TelemetryModule) | - |
+| [TelemetryRuleEngine](Class.TelemetryRuleEngine) | - |
+
+## Interfaces
+
+| Interface | Description |
+| ------ | ------ |
+| [IMetricInstruments](Interface.IMetricInstruments) | - |
+| [ITelemetryFacade](Interface.ITelemetryFacade) | - |
+| [ITelemetryMetricsOptions](Interface.ITelemetryMetricsOptions) | - |
+| [ITelemetryOptions](Interface.ITelemetryOptions) | - |
+| [ITelemetryTracesOptions](Interface.ITelemetryTracesOptions) | - |
+
+## Variables
+
+| Variable | Description |
+| ------ | ------ |
+| [defaultTelemetryOptions](Variable.defaultTelemetryOptions) | - |
+| [TELEMETRY\_ENABLED](Variable.TELEMETRY_ENABLED) | - |
+| [TELEMETRY\_FACADE](Variable.TELEMETRY_FACADE) | - |
+| [TELEMETRY\_OPTIONS](Variable.TELEMETRY_OPTIONS) | - |
+
+## Functions
+
+| Function | Description |
+| ------ | ------ |
+| [validateTelemetryOptions](Function.validateTelemetryOptions) | Validates telemetry options and throws on invalid values. |

package/data/packages/platform-telemetry/index.md

@@ -0,0 +1,234 @@
+---
+title: platform-telemetry
+description: OpenTelemetry integration with tracing, metrics, and graceful no-op fallback.
+order: 11
+tags: [telemetry, opentelemetry, tracing, metrics, observability]
+package: '@breadstone/archipel-platform-telemetry'
+---
+
+# platform-telemetry
+
+OpenTelemetry integration providing distributed tracing, metrics collection, and a graceful no-op fallback when telemetry is disabled. Wraps the OTEL SDK with a clean facade pattern.
+
+**Package:** `@breadstone/archipel-platform-telemetry`
+
+## Quick Start
+
+```typescript
+import { Module } from '@nestjs/common';
+import { TelemetryModule } from '@breadstone/archipel-platform-telemetry';
+
+@Module({
+  imports: [
+    TelemetryModule.register({
+      enabled: true,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+---
+
+## Module Configuration
+
+### ITelemetryOptions
+
+| Property  | Type      | Default | Description              |
+| --------- | --------- | ------- | ------------------------ |
+| `enabled` | `boolean` | `false` | Enable/disable telemetry |
+
+When disabled, the `NoopTelemetryFacade` is injected instead — all method calls are no-ops with zero overhead.
+
+```typescript
+// Disabled telemetry — safe, no-overhead
+TelemetryModule.register({ enabled: false });
+
+// Enabled telemetry — full OTEL SDK
+TelemetryModule.register({ enabled: true });
+```
+
+---
+
+## TelemetryFacade
+
+Main API for recording operations, cache events, and custom metrics.
+
+### Wrap Operations
+
+Automatically trace async operations with duration, success/failure status, and error capture:
+
+```typescript
+import { TelemetryFacade, TELEMETRY_FACADE } from '@breadstone/archipel-platform-telemetry';
+
+@Injectable()
+export class OrderService {
+  constructor(@Inject(TELEMETRY_FACADE) private readonly _telemetry: TelemetryFacade) {}
+
+  public async processOrder(orderId: string): Promise<IOrder> {
+    return this._telemetry.runOperation('processOrder', async () => {
+      const order = await this._orderRepo.findById(orderId);
+      await this._paymentService.charge(order);
+      await this._inventoryService.reserve(order.items);
+      return order;
+    });
+    // Automatically records:
+    // - operation.name = 'processOrder'
+    // - duration_ms
+    // - status = 'success' | 'error'
+    // - error details (if thrown)
+  }
+}
+```
+
+### Record Cache Events
+
+Track cache hits and misses:
+
+```typescript
+this._telemetry.recordCacheEvent({
+  cache: 'products',
+  outcome: 'hit', // 'hit' | 'miss'
+  phase: 'memory', // optional: 'memory' | 'redis' | 'db'
+});
+```
+
+### Record Custom Metrics
+
+```typescript
+this._telemetry.recordClientMetric('order_total_amount', 'histogram', order.total, { currency: 'EUR', region: 'DE' });
+```
+
+### Get Logger
+
+```typescript
+const logger = this._telemetry.getLogger();
+logger.log('Order processed', { orderId, total: order.total });
+```
+
+---
+
+## TelemetryCacheMetricsRecorder
+
+Bridges the `ICacheMetricsRecorder` interface (from `platform-core`) with the telemetry facade:
+
+```typescript
+import { TelemetryCacheMetricsRecorder } from '@breadstone/archipel-platform-telemetry';
+import { MemoryLayeredCache } from '@breadstone/archipel-platform-core';
+
+// In a module provider
+{
+    provide: 'PRODUCT_CACHE',
+    useFactory: (recorder: TelemetryCacheMetricsRecorder) => {
+        return new MemoryLayeredCache<string, IProduct>(
+            async (key) => fetchProduct(key),
+            {
+                ttlMs: 60_000,
+                metricsRecorder: recorder,
+                cacheName: 'products',
+            }
+        );
+    },
+    inject: [TelemetryCacheMetricsRecorder],
+}
+```
+
+---
+
+## TelemetryRuleEngine
+
+Conditionally enable/disable telemetry recording per operation:
+
+```typescript
+import { TelemetryRuleEngine } from '@breadstone/archipel-platform-telemetry';
+
+@Injectable()
+export class AppTelemetryRules extends TelemetryRuleEngine {
+  public shouldRecord(operationName: string): boolean {
+    // Skip noisy health checks
+    if (operationName === 'healthCheck') return false;
+    return true;
+  }
+}
+```
+
+---
+
+## OpenTelemetry Internals
+
+The module initializes these OTEL components:
+
+| Component               | Implementation                           |
+| ----------------------- | ---------------------------------------- |
+| Trace exporter          | OTLP/HTTP                                |
+| Metrics exporter        | OTLP/HTTP                                |
+| Express instrumentation | `@opentelemetry/instrumentation-express` |
+| HTTP instrumentation    | `@opentelemetry/instrumentation-http`    |
+| SDK shutdown hook       | Graceful on `OnModuleDestroy`            |
+
+---
+
+## Real-World Example: Full Observability Stack
+
+```typescript
+@Module({
+  imports: [
+    TelemetryModule.register({ enabled: process.env.OTEL_ENABLED === 'true' }),
+    LoggerModule, // Sentry integration
+    DatabaseModule.forRoot(),
+  ],
+})
+export class AppModule {}
+
+// In a service
+@Injectable()
+export class ProductService {
+  constructor(
+    @Inject(TELEMETRY_FACADE) private readonly _telemetry: TelemetryFacade,
+    private readonly _analytics: AnalyticsService,
+    private readonly _productRepo: ProductRepository,
+  ) {}
+
+  public async searchProducts(query: string): Promise<IProduct[]> {
+    return this._telemetry.runOperation('searchProducts', async () => {
+      const results = await this._productRepo.execute(searchProducts(query));
+
+      this._telemetry.recordClientMetric('search_results_count', 'histogram', results.length, {
+        query_length: query.length.toString(),
+      });
+
+      return results;
+    });
+  }
+}
+```
+
+---
+
+## Graceful Degradation
+
+When `enabled: false` or when the OTEL SDK fails to initialize:
+
+- `NoopTelemetryFacade` is injected instead of `TelemetryFacade`
+- All operations execute normally without tracing overhead
+- `runOperation()` simply invokes the callback
+- `recordCacheEvent()` and `recordClientMetric()` are no-ops
+- No errors thrown — the application runs normally
+
+---
+
+## Exports Summary
+
+| Export                          | Type          | Description                |
+| ------------------------------- | ------------- | -------------------------- |
+| `TelemetryModule`               | NestJS Module | `register()` configuration |
+| `TelemetryFacade`               | Service       | Main telemetry API         |
+| `NoopTelemetryFacade`           | Service       | Disabled-mode fallback     |
+| `TelemetryCacheMetricsRecorder` | Service       | Bridge for cache metrics   |
+| `TelemetryRuleEngine`           | Service       | Conditional recording      |
+| `TelemetryLoggerService`        | Service       | Logger integration         |
+| `OperationTelemetryInterceptor` | Interceptor   | Auto-trace HTTP requests (returns `Observable<unknown>`) |
+| `TELEMETRY_FACADE`              | Token         | Injection token for facade |
+| `TELEMETRY_ENABLED`             | Token         | Boolean enabled flag       |
+| `TELEMETRY_OPTIONS`             | Token         | Configuration options      |
+| `TELEMETRY_SHUTDOWN`            | Token         | Shutdown hook              |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breadstone/archipel-mcp",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "MCP server providing Archipel platform knowledge — documentation, query patterns, and coding conventions — to AI development tools.",
   "type": "commonjs",
   "main": "./src/main.js",