@nage-api/observability 1.0.0-beta.2

package/dist/observability.module.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * `NageObservabilityModule.forRoot(config)` (PLAN.md §11.1 item 6, §21).
+ *
+ * Each of the three concerns is independently switchable, and each contributes
+ * **no provider** when it is off — a metrics registry nobody scrapes is still a
+ * map that grows.
+ *
+ * Health is the exception: it is always registered, because liveness and
+ * readiness are not optional in a deployed system, and a probe endpoint that
+ * exists only when a feature flag says so is a probe that will be missing on
+ * the day it matters.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var NageObservabilityModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NageObservabilityModule = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const health_controller_js_1 = require("./health.controller.js");
+const health_js_1 = require("./health.js");
+const http_interceptor_js_1 = require("./http.interceptor.js");
+const metrics_js_1 = require("./metrics.js");
+const tracing_js_1 = require("./tracing.js");
+const tokens_js_1 = require("./tokens.js");
+let NageObservabilityModule = NageObservabilityModule_1 = class NageObservabilityModule {
+    static forRoot(options = {}) {
+        const config = options.observability ?? {};
+        const health = new health_js_1.HealthRegistry({
+            ...(options.healthTimeoutMs === undefined ? {} : { timeoutMs: options.healthTimeoutMs }),
+            ...(options.clock === undefined ? {} : { clock: options.clock }),
+        });
+        for (const check of options.checks ?? [])
+            health.register(check);
+        const metricsEnabled = config.metrics?.enabled === true;
+        const registry = metricsEnabled ? new metrics_js_1.MetricsRegistry() : undefined;
+        const metrics = options.metrics ?? registry ?? new metrics_js_1.NoopMetrics();
+        const tracingEnabled = config.tracing?.enabled === true;
+        // A no-op tracer is not a disabled feature: the framework's own spans are
+        // unconditional, and the tracer decides whether they cost anything.
+        const tracer = tracingEnabled
+            ? (options.tracer ?? new tracing_js_1.NoopTracer())
+            : new tracing_js_1.NoopTracer();
+        const providers = [
+            { provide: tokens_js_1.NAGE_HEALTH, useValue: health },
+            { provide: health_js_1.HealthRegistry, useValue: health },
+            { provide: tokens_js_1.NAGE_TRACER, useValue: tracer },
+            { provide: tokens_js_1.NAGE_METRICS, useValue: metrics },
+            { provide: tokens_js_1.NAGE_HEALTH_EXPOSE_DETAIL, useValue: options.exposeHealthDetail ?? false },
+        ];
+        const controllers = [health_controller_js_1.HealthController];
+        if (registry !== undefined) {
+            providers.push({ provide: tokens_js_1.NAGE_METRICS_REGISTRY, useValue: registry }, { provide: metrics_js_1.MetricsRegistry, useValue: registry });
+            controllers.push(health_controller_js_1.MetricsController);
+        }
+        // Tracing counts too, not only metrics: the interceptor is the one thing in
+        // the framework that opens a request span, so gating it on the registry
+        // alone left `tracing.enabled` with nothing to drive and an application's
+        // bound adapter silently idle.
+        if (registry !== undefined || tracingEnabled) {
+            providers.push({
+                provide: core_1.APP_INTERCEPTOR,
+                useValue: new http_interceptor_js_1.HttpObservabilityInterceptor({
+                    metrics,
+                    tracer,
+                    ...(options.clock === undefined ? {} : { clock: options.clock }),
+                }),
+            });
+        }
+        return {
+            module: NageObservabilityModule_1,
+            controllers,
+            providers,
+            exports: [
+                tokens_js_1.NAGE_HEALTH,
+                health_js_1.HealthRegistry,
+                tokens_js_1.NAGE_TRACER,
+                tokens_js_1.NAGE_METRICS,
+                ...(registry === undefined ? [] : [tokens_js_1.NAGE_METRICS_REGISTRY, metrics_js_1.MetricsRegistry]),
+            ],
+        };
+    }
+};
+exports.NageObservabilityModule = NageObservabilityModule;
+exports.NageObservabilityModule = NageObservabilityModule = NageObservabilityModule_1 = __decorate([
+    (0, common_1.Module)({})
+], NageObservabilityModule);
+//# sourceMappingURL=observability.module.js.map

package/dist/ports.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Observability ports (PLAN.md §18, §21, §25 P1).
+ *
+ * Three concerns, three ports, all of which the framework already needs
+ * somewhere: `LoggerPort` (already in `@nage-api/contracts`, so logging swaps
+ * without a caller changing), tracing, and metrics.
+ *
+ * OpenTelemetry is a large dependency with a large surface. Rather than take
+ * it, this package states the small part of it the framework uses and ships a
+ * no-op default; an application that wants real tracing binds an adapter. The
+ * framework's own spans then cost nothing when nobody is collecting them, which
+ * is the normal case in development and in tests.
+ */
+/** A unit of work in a trace. */
+export interface Span {
+    /** Attach structured detail; never a credential or a request body. */
+    setAttribute(key: string, value: string | number | boolean): void;
+    /** Record a failure against the span without ending it. */
+    recordError(error: unknown): void;
+    end(): void;
+}
+export interface SpanOptions {
+    readonly attributes?: Readonly<Record<string, string | number | boolean>>;
+    /** `server` for an inbound request, `client` for an outbound call. */
+    readonly kind?: 'internal' | 'server' | 'client' | 'producer' | 'consumer';
+}
+export interface TracerPort {
+    startSpan(name: string, options?: SpanOptions): Span;
+    /** Run `fn` inside a span, ending it — and recording a failure — either way. */
+    trace<TResult>(name: string, fn: (span: Span) => Promise<TResult>, options?: SpanOptions): Promise<TResult>;
+}
+/** Label set attached to a metric sample. Cardinality is the caller's problem. */
+export type MetricLabels = Readonly<Record<string, string>>;
+export interface MetricsPort {
+    increment(name: string, value?: number, labels?: MetricLabels): void;
+    /** Set an absolute value, e.g. a queue depth. */
+    gauge(name: string, value: number, labels?: MetricLabels): void;
+    /** Record an observation into a histogram, e.g. a request duration. */
+    observe(name: string, value: number, labels?: MetricLabels): void;
+}
+/** One dependency's answer to "are you ready?" (PLAN.md §21). */
+export type HealthStatus = 'up' | 'down' | 'degraded';
+export interface HealthCheckResult {
+    readonly name: string;
+    readonly status: HealthStatus;
+    /** Milliseconds the probe took; useful for spotting a slow dependency. */
+    readonly durationMs: number;
+    /** Operator-facing detail. Never returned to an unauthenticated caller. */
+    readonly detail?: string;
+}
+export interface HealthReport {
+    readonly status: HealthStatus;
+    readonly checks: readonly HealthCheckResult[];
+}
+/**
+ * A readiness probe.
+ *
+ * `critical: false` marks a dependency the application can serve without —
+ * a cache, say. It degrades the report rather than failing it, so a Redis
+ * outage does not take the whole deployment out of the load balancer.
+ */
+export interface HealthCheck {
+    readonly name: string;
+    readonly critical?: boolean;
+    /** Should resolve quickly; the registry applies its own timeout regardless. */
+    check(): Promise<void>;
+}
+/** Injected so timings and TTLs are testable without waiting. */
+export interface Clock {
+    now(): number;
+}
+export declare const systemClock: Clock;
+//# sourceMappingURL=ports.d.ts.map

package/dist/ports.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Observability ports (PLAN.md §18, §21, §25 P1).
+ *
+ * Three concerns, three ports, all of which the framework already needs
+ * somewhere: `LoggerPort` (already in `@nage-api/contracts`, so logging swaps
+ * without a caller changing), tracing, and metrics.
+ *
+ * OpenTelemetry is a large dependency with a large surface. Rather than take
+ * it, this package states the small part of it the framework uses and ships a
+ * no-op default; an application that wants real tracing binds an adapter. The
+ * framework's own spans then cost nothing when nobody is collecting them, which
+ * is the normal case in development and in tests.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemClock = void 0;
+exports.systemClock = { now: () => Date.now() };
+//# sourceMappingURL=ports.js.map

package/dist/tokens.d.ts

@@ -0,0 +1,19 @@
+/** DI tokens for the observability ports (PLAN.md §7.3). */
+import { type Token } from '@nage-api/core';
+import type { HealthRegistry } from './health.js';
+import type { MetricsPort, TracerPort } from './ports.js';
+import type { MetricsRegistry } from './metrics.js';
+/** What application code injects to record a metric. */
+export declare const NAGE_METRICS: Token<MetricsPort>;
+/** The concrete registry, for a scrape endpoint or a diagnostic dump. */
+export declare const NAGE_METRICS_REGISTRY: Token<MetricsRegistry>;
+export declare const NAGE_TRACER: Token<TracerPort>;
+export declare const NAGE_HEALTH: Token<HealthRegistry>;
+/**
+ * Whether `/health/ready` returns each failing check's message.
+ *
+ * A token rather than a controller constructor argument, because a probe
+ * endpoint is unauthenticated and this is the switch that decides what leaks.
+ */
+export declare const NAGE_HEALTH_EXPOSE_DETAIL: Token<boolean>;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.js

@@ -0,0 +1,19 @@
+"use strict";
+/** DI tokens for the observability ports (PLAN.md §7.3). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAGE_HEALTH_EXPOSE_DETAIL = exports.NAGE_HEALTH = exports.NAGE_TRACER = exports.NAGE_METRICS_REGISTRY = exports.NAGE_METRICS = void 0;
+const core_1 = require("@nage-api/core");
+/** What application code injects to record a metric. */
+exports.NAGE_METRICS = (0, core_1.createToken)('NAGE_METRICS');
+/** The concrete registry, for a scrape endpoint or a diagnostic dump. */
+exports.NAGE_METRICS_REGISTRY = (0, core_1.createToken)('NAGE_METRICS_REGISTRY');
+exports.NAGE_TRACER = (0, core_1.createToken)('NAGE_TRACER');
+exports.NAGE_HEALTH = (0, core_1.createToken)('NAGE_HEALTH');
+/**
+ * Whether `/health/ready` returns each failing check's message.
+ *
+ * A token rather than a controller constructor argument, because a probe
+ * endpoint is unauthenticated and this is the switch that decides what leaks.
+ */
+exports.NAGE_HEALTH_EXPOSE_DETAIL = (0, core_1.createToken)('NAGE_HEALTH_EXPOSE_DETAIL');
+//# sourceMappingURL=tokens.js.map

package/dist/tracing.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Tracing behind a port, with a no-op default (PLAN.md §18).
+ *
+ * The framework's own instrumentation — a span per request, per query, per
+ * outbound call — should cost nothing when nobody is collecting. `NoopTracer`
+ * is what makes that true, and it is what runs in development and in tests.
+ *
+ * `RecordingTracer` is the same interface backed by memory: a test can assert
+ * that a span was opened, that it carried the right attributes, and that a
+ * failure was recorded on it, without an OTel collector.
+ */
+import type { Clock, Span, SpanOptions, TracerPort } from './ports.js';
+/** Discards everything. Allocation-free apart from the shared span object. */
+export declare class NoopTracer implements TracerPort {
+    #private;
+    startSpan(): Span;
+    trace<TResult>(_name: string, fn: (span: Span) => Promise<TResult>): Promise<TResult>;
+}
+export interface RecordedSpan {
+    readonly name: string;
+    readonly kind: string;
+    readonly startedAt: number;
+    endedAt?: number;
+    readonly attributes: Record<string, string | number | boolean>;
+    readonly errors: string[];
+}
+export interface RecordingTracerOptions {
+    readonly clock?: Clock;
+    /** Keep at most this many spans; a tracer must not become a memory leak. */
+    readonly maxSpans?: number;
+}
+export declare class RecordingTracer implements TracerPort {
+    #private;
+    constructor(options?: RecordingTracerOptions);
+    startSpan(name: string, options?: SpanOptions): Span;
+    trace<TResult>(name: string, fn: (span: Span) => Promise<TResult>, options?: SpanOptions): Promise<TResult>;
+    get spans(): readonly RecordedSpan[];
+    find(name: string): RecordedSpan | undefined;
+    clear(): void;
+}
+//# sourceMappingURL=tracing.d.ts.map

package/dist/tracing.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Tracing behind a port, with a no-op default (PLAN.md §18).
+ *
+ * The framework's own instrumentation — a span per request, per query, per
+ * outbound call — should cost nothing when nobody is collecting. `NoopTracer`
+ * is what makes that true, and it is what runs in development and in tests.
+ *
+ * `RecordingTracer` is the same interface backed by memory: a test can assert
+ * that a span was opened, that it carried the right attributes, and that a
+ * failure was recorded on it, without an OTel collector.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecordingTracer = exports.NoopTracer = void 0;
+const core_1 = require("@nage-api/core");
+/** Discards everything. Allocation-free apart from the shared span object. */
+class NoopTracer {
+    static #span = {
+        setAttribute: () => undefined,
+        recordError: () => undefined,
+        end: () => undefined,
+    };
+    startSpan() {
+        return NoopTracer.#span;
+    }
+    async trace(_name, fn) {
+        return fn(NoopTracer.#span);
+    }
+}
+exports.NoopTracer = NoopTracer;
+const DEFAULT_MAX_SPANS = 1000;
+class RecordingTracer {
+    #spans = [];
+    #clock;
+    #maxSpans;
+    constructor(options = {}) {
+        this.#clock = options.clock ?? { now: () => Date.now() };
+        this.#maxSpans = options.maxSpans ?? DEFAULT_MAX_SPANS;
+    }
+    startSpan(name, options = {}) {
+        const recorded = {
+            name,
+            kind: options.kind ?? 'internal',
+            startedAt: this.#clock.now(),
+            attributes: { ...options.attributes },
+            errors: [],
+        };
+        // The correlation id is what ties a span to the log lines and the response
+        // envelope for the same request, so it is attached rather than left to
+        // every caller to remember.
+        const requestId = (0, core_1.getActiveContext)()?.requestId;
+        if (requestId !== undefined)
+            recorded.attributes['request.id'] = requestId;
+        this.#spans.push(recorded);
+        if (this.#spans.length > this.#maxSpans)
+            this.#spans.shift();
+        return {
+            setAttribute: (key, value) => {
+                // Attributes reach a collector a team may not control, so the same
+                // redaction that guards log lines guards them.
+                recorded.attributes[key] = typeof value === 'string' ? redactValue(key, value) : value;
+            },
+            recordError: (error) => {
+                recorded.errors.push(error instanceof Error ? error.message : String(error));
+            },
+            end: () => {
+                recorded.endedAt = this.#clock.now();
+            },
+        };
+    }
+    async trace(name, fn, options = {}) {
+        const span = this.startSpan(name, options);
+        try {
+            return await fn(span);
+        }
+        catch (error) {
+            span.recordError(error);
+            throw error;
+        }
+        finally {
+            // In `finally`, so a thrown error still closes the span. An unclosed span
+            // is worse than no span: it shows as an operation that never returned.
+            span.end();
+        }
+    }
+    get spans() {
+        return this.#spans;
+    }
+    find(name) {
+        return this.#spans.find((span) => span.name === name);
+    }
+    clear() {
+        this.#spans.length = 0;
+    }
+}
+exports.RecordingTracer = RecordingTracer;
+const REDACTED_ATTRIBUTES = (0, core_1.redactionSet)();
+function redactValue(key, value) {
+    const redacted = (0, core_1.redact)({ [key]: value }, REDACTED_ATTRIBUTES);
+    const result = redacted[key];
+    return typeof result === 'string' ? result : value;
+}
+//# sourceMappingURL=tracing.js.map

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@nage-api/observability",
+  "version": "1.0.0-beta.2",
+  "description": "Logging, tracing, metrics and health for @nage-api",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "!dist/**/*.map",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nage-api/contracts": "1.0.0-beta.2",
+    "@nage-api/core": "1.0.0-beta.2"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "reflect-metadata": "^0.2.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "11.1.29",
+    "@nestjs/core": "11.1.29",
+    "@nestjs/platform-express": "11.1.29",
+    "@nestjs/testing": "11.1.29",
+    "@swc/core": "1.15.47",
+    "@types/node": "22.20.1",
+    "@types/supertest": "6.0.3",
+    "@vitest/coverage-v8": "4.1.10",
+    "reflect-metadata": "0.2.2",
+    "rimraf": "6.1.3",
+    "rxjs": "7.8.2",
+    "supertest": "7.1.4",
+    "typescript": "5.9.3",
+    "unplugin-swc": "1.5.11",
+    "vitest": "4.1.10",
+    "@nage-api/testing": "1.0.0-beta.2"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "clean": "rimraf dist .turbo",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}