@nathapp/nestjs-observability

First-party metrics (Prometheus) and distributed tracing (OpenTelemetry) for NestJS, joined to the nathapp correlation-id context so logs, metrics, and traces share one id.

Status: scaffolded. Behaviour is implemented per docs/superpowers/specs/2026-07-07-nestjs-observability-design.md — files under lib/** currently throw not implemented and are filled in by the TDD plan.

What it provides

• RED HTTP metrics — request count, error count, and a duration histogram (labelled method/route/status) via a global interceptor, plus default Node/process metrics.
• /metrics scrape endpoint — powered by @willsoto/nestjs-prometheus. Path is configurable. Exposure and authz are the consumer's concern (no auth is applied).
• Distributed tracing — an OpenTelemetry NodeSDK with HTTP + express/fastify auto-instrumentation, OTLP/console exporters, and a configurable sampling ratio.
• Correlation bridge — the request correlation id (nestjs-logging RequestContextService) is set on each span, and the active trace_id/span_id are written back into the logging context so log lines carry them.
• Manual spans — a TraceService and a @Trace() method decorator.
• Custom metrics — makeCounterProvider / makeGaugeProvider / makeHistogramProvider / makeSummaryProvider / InjectMetric are re-exported so you never depend on @willsoto/nestjs-prometheus directly.

Usage

Tracing must start before any framework import, so call initTracing() first in main.ts:

// main.ts — very first lines
import { initTracing } from '@nathapp/nestjs-observability';
initTracing({ serviceName: 'my-api', otlpUrl: process.env.OTLP_URL });

// ...then the normal bootstrap
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
bootstrap();

Register the module for metrics + in-app trace helpers:

import { ObservabilityModule } from '@nathapp/nestjs-observability';

@Module({
  imports: [
    ObservabilityModule.register({
      metrics: { path: '/metrics', ignoreRoutes: ['/metrics', '/health'] },
      tracing: { correlationBridge: true },
    }),
  ],
})
export class AppModule {}

Peer dependencies

• @nestjs/common, @nestjs/core, rxjs — the framework.
• @nathapp/nestjs-logging — soft; only the correlation bridge uses its RequestContextService. Without it the bridge is inert (everything else still works).

Scope (v1)

Metrics are pure Prometheus; OpenTelemetry is tracing-only. OTel metrics, OTLP logs, DB/Redis/queue instrumentation, exemplars, and dashboards are deferred follow-ups.