@breadstone/archipel-platform-telemetry

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

import { TelemetryModule } from '@breadstone/archipel-platform-telemetry';

// Health indicator (optional)
import { TelemetryHealthIndicator } from '@breadstone/archipel-platform-telemetry/health';

@Module({
  imports: [TelemetryModule],
})
export class AppModule {}

Lifecycle

• Startup (OnModuleInit): MetricsService creates metric instruments eagerly.
• Shutdown: SDK shutdown is capped at 5 seconds to prevent hanging processes.

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 |

Documentation

📖 Telemetry Guide: .docs/guides/telemetry-and-observability.md

Development

# Build
yarn nx build platform-telemetry

# Test
yarn nx test platform-telemetry

# Lint
yarn nx lint platform-telemetry