@nage-api/observability 1.0.0-beta.2

package/dist/health.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Readiness and liveness (PLAN.md §21).
+ *
+ * Liveness answers "is this process wedged?" — it must not touch a dependency,
+ * because a database outage restarting every pod turns a degraded system into
+ * an outage. Readiness answers "should traffic come here?" and does check
+ * dependencies.
+ *
+ * Two things the legacy framework got wrong and this fixes:
+ *
+ * **A slow probe is a failing probe.** Every check runs under a timeout, so a
+ * dependency that hangs is reported as down in bounded time rather than holding
+ * the probe open until the orchestrator's own timeout fires.
+ *
+ * **Not every dependency is critical.** A cache being down should degrade the
+ * report, not fail it — pulling a node out of the load balancer because Redis
+ * blinked makes the outage worse.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HealthRegistry = void 0;
+exports.healthCheck = healthCheck;
+const DEFAULT_TIMEOUT_MS = 2000;
+class HealthRegistry {
+    #checks = new Map();
+    #timeoutMs;
+    #clock;
+    constructor(options = {}) {
+        this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.#clock = options.clock ?? { now: () => Date.now() };
+    }
+    register(check) {
+        this.#checks.set(check.name, check);
+        return this;
+    }
+    unregister(name) {
+        this.#checks.delete(name);
+        return this;
+    }
+    get names() {
+        return [...this.#checks.keys()];
+    }
+    /**
+     * Run every check.
+     *
+     * Concurrently, because readiness is polled every few seconds and running ten
+     * probes in series makes the probe itself the slow dependency.
+     */
+    async check() {
+        const results = await Promise.all([...this.#checks.values()].map((check) => this.#run(check)));
+        const critical = [...this.#checks.values()].filter((check) => check.critical !== false);
+        const criticalNames = new Set(critical.map((check) => check.name));
+        const failedCritical = results.some((result) => result.status === 'down' && criticalNames.has(result.name));
+        const failedOptional = results.some((result) => result.status === 'down');
+        const status = failedCritical ? 'down' : failedOptional ? 'degraded' : 'up';
+        return { status, checks: results };
+    }
+    async #run(check) {
+        const startedAt = this.#clock.now();
+        let timer;
+        try {
+            await Promise.race([
+                check.check(),
+                new Promise((_resolve, reject) => {
+                    timer = setTimeout(() => {
+                        reject(new Error(`timed out after ${String(this.#timeoutMs)}ms`));
+                    }, this.#timeoutMs);
+                    timer.unref();
+                }),
+            ]);
+            return { name: check.name, status: 'up', durationMs: this.#clock.now() - startedAt };
+        }
+        catch (error) {
+            return {
+                name: check.name,
+                status: 'down',
+                durationMs: this.#clock.now() - startedAt,
+                // Operator-facing. The controller decides what an unauthenticated
+                // caller sees, and by default it is nothing but the status.
+                detail: error instanceof Error ? error.message : String(error),
+            };
+        }
+        finally {
+            // Always cleared: a pending timer per probe, every few seconds, is a leak
+            // that only shows up after a week of uptime.
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+}
+exports.HealthRegistry = HealthRegistry;
+/** Build a check from any async probe — a `SELECT 1`, a `PING`, a HEAD request. */
+function healthCheck(name, probe, options = {}) {
+    return {
+        name,
+        ...(options.critical === undefined ? {} : { critical: options.critical }),
+        check: async () => {
+            await probe();
+        },
+    };
+}
+//# sourceMappingURL=health.js.map

package/dist/http.interceptor.d.ts

@@ -0,0 +1,41 @@
+/**
+ * One interceptor that times every request, counts it, and traces it
+ * (PLAN.md §18, §21).
+ *
+ * The route **template** is the metric label, never the resolved path:
+ * `/orders/:id` is one time series, `/orders/1`…`/orders/9999999` is a
+ * cardinality explosion that eventually takes the scraper down. That single
+ * decision is most of what makes HTTP metrics safe to leave on.
+ */
+import { type CallHandler, type ExecutionContext, type NestInterceptor } from '@nestjs/common';
+import { type Observable } from 'rxjs';
+import type { Clock, MetricsPort, TracerPort } from './ports.js';
+interface RequestLike {
+    method?: string;
+    route?: {
+        path?: string;
+    };
+    url?: string;
+}
+export interface HttpObservabilityOptions {
+    readonly metrics: MetricsPort;
+    readonly tracer: TracerPort;
+    readonly clock?: Clock;
+}
+export declare const HTTP_REQUESTS_TOTAL = "nage_http_requests_total";
+export declare const HTTP_DURATION_MS = "nage_http_request_duration_ms";
+export declare const HTTP_IN_FLIGHT = "nage_http_requests_in_flight";
+export declare class HttpObservabilityInterceptor implements NestInterceptor {
+    #private;
+    constructor(options: HttpObservabilityOptions);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
+/**
+ * The route template, or `unknown`.
+ *
+ * Never the resolved URL: one series per id is how a metrics endpoint grows
+ * without bound.
+ */
+export declare function routeTemplate(request: RequestLike): string;
+export {};
+//# sourceMappingURL=http.interceptor.d.ts.map

package/dist/http.interceptor.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * One interceptor that times every request, counts it, and traces it
+ * (PLAN.md §18, §21).
+ *
+ * The route **template** is the metric label, never the resolved path:
+ * `/orders/:id` is one time series, `/orders/1`…`/orders/9999999` is a
+ * cardinality explosion that eventually takes the scraper down. That single
+ * decision is most of what makes HTTP metrics safe to leave on.
+ */
+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 __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpObservabilityInterceptor = exports.HTTP_IN_FLIGHT = exports.HTTP_DURATION_MS = exports.HTTP_REQUESTS_TOTAL = void 0;
+exports.routeTemplate = routeTemplate;
+const common_1 = require("@nestjs/common");
+const rxjs_1 = require("rxjs");
+exports.HTTP_REQUESTS_TOTAL = 'nage_http_requests_total';
+exports.HTTP_DURATION_MS = 'nage_http_request_duration_ms';
+exports.HTTP_IN_FLIGHT = 'nage_http_requests_in_flight';
+let HttpObservabilityInterceptor = class HttpObservabilityInterceptor {
+    #metrics;
+    #tracer;
+    #clock;
+    #inFlight = 0;
+    constructor(options) {
+        this.#metrics = options.metrics;
+        this.#tracer = options.tracer;
+        this.#clock = options.clock ?? { now: () => Date.now() };
+    }
+    intercept(context, next) {
+        if (context.getType() !== 'http')
+            return next.handle();
+        const http = context.switchToHttp();
+        const request = http.getRequest();
+        const method = request.method ?? 'GET';
+        const route = routeTemplate(request);
+        const startedAt = this.#clock.now();
+        this.#inFlight += 1;
+        this.#metrics.gauge(exports.HTTP_IN_FLIGHT, this.#inFlight);
+        const span = this.#tracer.startSpan(`${method} ${route}`, {
+            kind: 'server',
+            attributes: { 'http.method': method, 'http.route': route },
+        });
+        let completed = false;
+        const complete = (status) => {
+            // One request, however many values the handler emits. A route that returns
+            // a multi-value observable — an SSE stream, say — otherwise decrements the
+            // in-flight gauge once per emission and drives it negative, while counting
+            // one request as several.
+            if (completed)
+                return;
+            completed = true;
+            this.#inFlight -= 1;
+            this.#metrics.gauge(exports.HTTP_IN_FLIGHT, this.#inFlight);
+            const labels = { method, route, status: String(status) };
+            this.#metrics.increment(exports.HTTP_REQUESTS_TOTAL, 1, labels);
+            this.#metrics.observe(exports.HTTP_DURATION_MS, this.#clock.now() - startedAt, { method, route });
+            span.setAttribute('http.status_code', status);
+            span.end();
+        };
+        return next.handle().pipe((0, rxjs_1.tap)(() => {
+            complete(http.getResponse().statusCode ?? 200);
+        }), (0, rxjs_1.catchError)((error) => {
+            span.recordError(error);
+            // The filter has not run yet, so the response carries no status: take
+            // it from the error where it has one, and fall back to 500.
+            complete(statusOf(error));
+            return (0, rxjs_1.throwError)(() => error);
+        }));
+    }
+};
+exports.HttpObservabilityInterceptor = HttpObservabilityInterceptor;
+exports.HttpObservabilityInterceptor = HttpObservabilityInterceptor = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object])
+], HttpObservabilityInterceptor);
+/**
+ * The route template, or `unknown`.
+ *
+ * Never the resolved URL: one series per id is how a metrics endpoint grows
+ * without bound.
+ */
+function routeTemplate(request) {
+    const path = request.route?.path;
+    if (typeof path === 'string' && path !== '')
+        return path;
+    return 'unknown';
+}
+function statusOf(error) {
+    if (typeof error !== 'object' || error === null)
+        return 500;
+    const candidate = error;
+    if (typeof candidate.httpStatus === 'number')
+        return candidate.httpStatus;
+    if (typeof candidate.status === 'number')
+        return candidate.status;
+    return 500;
+}
+//# sourceMappingURL=http.interceptor.js.map

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `@nage-api/observability` — logging, tracing, metrics and health (PLAN.md §18,
+ * §21, §25 P1).
+ *
+ * Ports with no-op defaults, so the framework's own instrumentation costs
+ * nothing when nobody is collecting, and an application that wants OpenTelemetry
+ * or Prometheus binds an adapter without a caller changing.
+ */
+export type * from '@nage-api/contracts';
+export { NageObservabilityModule, type NageObservabilityModuleOptions, } from './observability.module.js';
+export { HealthRegistry, healthCheck, type HealthRegistryOptions } from './health.js';
+export { HealthController, MetricsController, type PublicHealthCheck, type PublicHealthReport, } from './health.controller.js';
+export { DEFAULT_BUCKETS, MetricsRegistry, NoopMetrics, renderLabels, type MetricSample, type MetricType, type MetricsRegistryOptions, } from './metrics.js';
+export { NoopTracer, RecordingTracer, type RecordedSpan, type RecordingTracerOptions, } from './tracing.js';
+export { HttpObservabilityInterceptor, HTTP_DURATION_MS, HTTP_IN_FLIGHT, HTTP_REQUESTS_TOTAL, routeTemplate, type HttpObservabilityOptions, } from './http.interceptor.js';
+export { NAGE_HEALTH, NAGE_HEALTH_EXPOSE_DETAIL, NAGE_METRICS, NAGE_METRICS_REGISTRY, NAGE_TRACER, } from './tokens.js';
+export { systemClock, type Clock, type HealthCheck, type HealthCheckResult, type HealthReport, type HealthStatus, type MetricLabels, type MetricsPort, type Span, type SpanOptions, type TracerPort, } from './ports.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * `@nage-api/observability` — logging, tracing, metrics and health (PLAN.md §18,
+ * §21, §25 P1).
+ *
+ * Ports with no-op defaults, so the framework's own instrumentation costs
+ * nothing when nobody is collecting, and an application that wants OpenTelemetry
+ * or Prometheus binds an adapter without a caller changing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemClock = exports.NAGE_TRACER = exports.NAGE_METRICS_REGISTRY = exports.NAGE_METRICS = exports.NAGE_HEALTH_EXPOSE_DETAIL = exports.NAGE_HEALTH = exports.routeTemplate = exports.HTTP_REQUESTS_TOTAL = exports.HTTP_IN_FLIGHT = exports.HTTP_DURATION_MS = exports.HttpObservabilityInterceptor = exports.RecordingTracer = exports.NoopTracer = exports.renderLabels = exports.NoopMetrics = exports.MetricsRegistry = exports.DEFAULT_BUCKETS = exports.MetricsController = exports.HealthController = exports.healthCheck = exports.HealthRegistry = exports.NageObservabilityModule = void 0;
+var observability_module_js_1 = require("./observability.module.js");
+Object.defineProperty(exports, "NageObservabilityModule", { enumerable: true, get: function () { return observability_module_js_1.NageObservabilityModule; } });
+var health_js_1 = require("./health.js");
+Object.defineProperty(exports, "HealthRegistry", { enumerable: true, get: function () { return health_js_1.HealthRegistry; } });
+Object.defineProperty(exports, "healthCheck", { enumerable: true, get: function () { return health_js_1.healthCheck; } });
+var health_controller_js_1 = require("./health.controller.js");
+Object.defineProperty(exports, "HealthController", { enumerable: true, get: function () { return health_controller_js_1.HealthController; } });
+Object.defineProperty(exports, "MetricsController", { enumerable: true, get: function () { return health_controller_js_1.MetricsController; } });
+var metrics_js_1 = require("./metrics.js");
+Object.defineProperty(exports, "DEFAULT_BUCKETS", { enumerable: true, get: function () { return metrics_js_1.DEFAULT_BUCKETS; } });
+Object.defineProperty(exports, "MetricsRegistry", { enumerable: true, get: function () { return metrics_js_1.MetricsRegistry; } });
+Object.defineProperty(exports, "NoopMetrics", { enumerable: true, get: function () { return metrics_js_1.NoopMetrics; } });
+Object.defineProperty(exports, "renderLabels", { enumerable: true, get: function () { return metrics_js_1.renderLabels; } });
+var tracing_js_1 = require("./tracing.js");
+Object.defineProperty(exports, "NoopTracer", { enumerable: true, get: function () { return tracing_js_1.NoopTracer; } });
+Object.defineProperty(exports, "RecordingTracer", { enumerable: true, get: function () { return tracing_js_1.RecordingTracer; } });
+var http_interceptor_js_1 = require("./http.interceptor.js");
+Object.defineProperty(exports, "HttpObservabilityInterceptor", { enumerable: true, get: function () { return http_interceptor_js_1.HttpObservabilityInterceptor; } });
+Object.defineProperty(exports, "HTTP_DURATION_MS", { enumerable: true, get: function () { return http_interceptor_js_1.HTTP_DURATION_MS; } });
+Object.defineProperty(exports, "HTTP_IN_FLIGHT", { enumerable: true, get: function () { return http_interceptor_js_1.HTTP_IN_FLIGHT; } });
+Object.defineProperty(exports, "HTTP_REQUESTS_TOTAL", { enumerable: true, get: function () { return http_interceptor_js_1.HTTP_REQUESTS_TOTAL; } });
+Object.defineProperty(exports, "routeTemplate", { enumerable: true, get: function () { return http_interceptor_js_1.routeTemplate; } });
+var tokens_js_1 = require("./tokens.js");
+Object.defineProperty(exports, "NAGE_HEALTH", { enumerable: true, get: function () { return tokens_js_1.NAGE_HEALTH; } });
+Object.defineProperty(exports, "NAGE_HEALTH_EXPOSE_DETAIL", { enumerable: true, get: function () { return tokens_js_1.NAGE_HEALTH_EXPOSE_DETAIL; } });
+Object.defineProperty(exports, "NAGE_METRICS", { enumerable: true, get: function () { return tokens_js_1.NAGE_METRICS; } });
+Object.defineProperty(exports, "NAGE_METRICS_REGISTRY", { enumerable: true, get: function () { return tokens_js_1.NAGE_METRICS_REGISTRY; } });
+Object.defineProperty(exports, "NAGE_TRACER", { enumerable: true, get: function () { return tokens_js_1.NAGE_TRACER; } });
+var ports_js_1 = require("./ports.js");
+Object.defineProperty(exports, "systemClock", { enumerable: true, get: function () { return ports_js_1.systemClock; } });
+//# sourceMappingURL=index.js.map

package/dist/metrics.d.ts

@@ -0,0 +1,63 @@
+/**
+ * An in-process metrics registry with Prometheus text exposition
+ * (PLAN.md §21).
+ *
+ * Small on purpose. A metrics client is not where a framework should spend a
+ * dependency: the exposition format is a dozen lines, and everything harder
+ * about metrics — cardinality, retention, aggregation — belongs to whatever
+ * scrapes them.
+ *
+ * The one thing this file takes seriously is **cardinality**. A label whose
+ * value comes from a request path or a user id creates a new time series per
+ * value, and a metrics endpoint that grows without bound will eventually take
+ * the scraper down with it. The registry caps series per metric and reports the
+ * overflow rather than silently dropping or silently growing.
+ */
+import type { MetricLabels, MetricsPort } from './ports.js';
+export type MetricType = 'counter' | 'gauge' | 'histogram';
+export interface MetricSample {
+    readonly name: string;
+    readonly type: MetricType;
+    readonly labels: MetricLabels;
+    readonly value: number;
+    /** Histograms only: observation count and sum, for computing an average. */
+    readonly count?: number;
+    readonly sum?: number;
+    readonly buckets?: Readonly<Record<string, number>>;
+}
+export interface MetricsRegistryOptions {
+    /** Distinct label combinations kept per metric name. */
+    readonly maxSeriesPerMetric?: number;
+    /** Histogram bucket boundaries, in the metric's own unit. */
+    readonly buckets?: readonly number[];
+}
+/** Latency buckets in milliseconds, spanning "fast" to "something is wrong". */
+export declare const DEFAULT_BUCKETS: readonly number[];
+export declare class MetricsRegistry implements MetricsPort {
+    #private;
+    constructor(options?: MetricsRegistryOptions);
+    increment(name: string, value?: number, labels?: MetricLabels): void;
+    gauge(name: string, value: number, labels?: MetricLabels): void;
+    observe(name: string, value: number, labels?: MetricLabels): void;
+    /** Every series currently held, for tests and for a JSON endpoint. */
+    snapshot(): readonly MetricSample[];
+    /** Samples dropped because a metric exceeded its series budget. */
+    get droppedSeries(): number;
+    reset(): void;
+    /** Prometheus text exposition, ready to serve from `/metrics`. */
+    render(): string;
+}
+/**
+ * A metrics port that discards everything; the default when metrics are off.
+ *
+ * The parameters are declared even though they are unused, so a caller written
+ * against `MetricsPort` type-checks against this implementation too.
+ */
+export declare class NoopMetrics implements MetricsPort {
+    increment(_name: string, _value?: number, _labels?: MetricLabels): void;
+    gauge(_name: string, _value: number, _labels?: MetricLabels): void;
+    observe(_name: string, _value: number, _labels?: MetricLabels): void;
+}
+/** Prometheus label syntax, with values escaped. */
+export declare function renderLabels(labels: MetricLabels): string;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * An in-process metrics registry with Prometheus text exposition
+ * (PLAN.md §21).
+ *
+ * Small on purpose. A metrics client is not where a framework should spend a
+ * dependency: the exposition format is a dozen lines, and everything harder
+ * about metrics — cardinality, retention, aggregation — belongs to whatever
+ * scrapes them.
+ *
+ * The one thing this file takes seriously is **cardinality**. A label whose
+ * value comes from a request path or a user id creates a new time series per
+ * value, and a metrics endpoint that grows without bound will eventually take
+ * the scraper down with it. The registry caps series per metric and reports the
+ * overflow rather than silently dropping or silently growing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoopMetrics = exports.MetricsRegistry = exports.DEFAULT_BUCKETS = void 0;
+exports.renderLabels = renderLabels;
+/** Latency buckets in milliseconds, spanning "fast" to "something is wrong". */
+exports.DEFAULT_BUCKETS = [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000];
+const DEFAULT_MAX_SERIES = 1000;
+class MetricsRegistry {
+    #series = new Map();
+    #seriesPerMetric = new Map();
+    #maxSeriesPerMetric;
+    #buckets;
+    #dropped = 0;
+    constructor(options = {}) {
+        this.#maxSeriesPerMetric = options.maxSeriesPerMetric ?? DEFAULT_MAX_SERIES;
+        this.#buckets = options.buckets ?? exports.DEFAULT_BUCKETS;
+    }
+    increment(name, value = 1, labels = {}) {
+        const series = this.#series0(name, 'counter', labels);
+        if (series === undefined)
+            return;
+        // A counter only ever goes up; a negative increment is a bug in the caller
+        // that would otherwise corrupt every rate computed from it.
+        series.value += Math.max(0, value);
+    }
+    gauge(name, value, labels = {}) {
+        const series = this.#series0(name, 'gauge', labels);
+        if (series === undefined)
+            return;
+        series.value = value;
+    }
+    observe(name, value, labels = {}) {
+        const series = this.#series0(name, 'histogram', labels);
+        if (series === undefined)
+            return;
+        series.count += 1;
+        series.sum += value;
+        for (const boundary of this.#buckets) {
+            if (value <= boundary) {
+                series.buckets.set(boundary, (series.buckets.get(boundary) ?? 0) + 1);
+            }
+        }
+    }
+    /** Every series currently held, for tests and for a JSON endpoint. */
+    snapshot() {
+        return [...this.#series.entries()].map(([key, series]) => ({
+            name: key.includes('{') ? key.slice(0, key.indexOf('{')) : key,
+            type: series.type,
+            labels: series.labels,
+            value: series.type === 'histogram' ? series.sum : series.value,
+            ...(series.type === 'histogram'
+                ? {
+                    count: series.count,
+                    sum: series.sum,
+                    buckets: Object.fromEntries([...series.buckets].map(([boundary, count]) => [String(boundary), count])),
+                }
+                : {}),
+        }));
+    }
+    /** Samples dropped because a metric exceeded its series budget. */
+    get droppedSeries() {
+        return this.#dropped;
+    }
+    reset() {
+        this.#series.clear();
+        this.#seriesPerMetric.clear();
+        this.#dropped = 0;
+    }
+    /** Prometheus text exposition, ready to serve from `/metrics`. */
+    render() {
+        const lines = [];
+        const seen = new Set();
+        for (const [key, series] of this.#series) {
+            const name = key.includes('{') ? key.slice(0, key.indexOf('{')) : key;
+            if (!seen.has(name)) {
+                seen.add(name);
+                lines.push(`# TYPE ${name} ${series.type}`);
+            }
+            const labels = renderLabels(series.labels);
+            if (series.type === 'histogram') {
+                for (const boundary of this.#buckets) {
+                    const bucketLabels = renderLabels({ ...series.labels, le: String(boundary) });
+                    lines.push(`${name}_bucket${bucketLabels} ${String(series.buckets.get(boundary) ?? 0)}`);
+                }
+                // `+Inf` is required by the format and equals the total observation count.
+                lines.push(`${name}_bucket${renderLabels({ ...series.labels, le: '+Inf' })} ${String(series.count)}`);
+                lines.push(`${name}_sum${labels} ${String(series.sum)}`);
+                lines.push(`${name}_count${labels} ${String(series.count)}`);
+                continue;
+            }
+            lines.push(`${name}${labels} ${String(series.value)}`);
+        }
+        if (this.#dropped > 0) {
+            lines.push('# TYPE nage_metrics_dropped_total counter');
+            lines.push(`nage_metrics_dropped_total ${String(this.#dropped)}`);
+        }
+        return `${lines.join('\n')}\n`;
+    }
+    /**
+     * Find or create a series, refusing to exceed the per-metric budget.
+     *
+     * Named with a trailing `0` because `#series` is the map; this returns one
+     * entry from it.
+     */
+    #series0(name, type, labels) {
+        const key = `${name}${renderLabels(labels)}`;
+        const existing = this.#series.get(key);
+        if (existing !== undefined)
+            return existing;
+        const count = this.#seriesPerMetric.get(name) ?? 0;
+        if (count >= this.#maxSeriesPerMetric) {
+            // Reported, not silent: a metrics endpoint that grows without bound takes
+            // the scraper down with it, and the operator should see why.
+            this.#dropped += 1;
+            return undefined;
+        }
+        const series = { type, labels, value: 0, count: 0, sum: 0, buckets: new Map() };
+        this.#series.set(key, series);
+        this.#seriesPerMetric.set(name, count + 1);
+        return series;
+    }
+}
+exports.MetricsRegistry = MetricsRegistry;
+/**
+ * A metrics port that discards everything; the default when metrics are off.
+ *
+ * The parameters are declared even though they are unused, so a caller written
+ * against `MetricsPort` type-checks against this implementation too.
+ */
+class NoopMetrics {
+    increment(_name, _value, _labels) {
+        // Intentionally empty.
+    }
+    gauge(_name, _value, _labels) {
+        // Intentionally empty.
+    }
+    observe(_name, _value, _labels) {
+        // Intentionally empty.
+    }
+}
+exports.NoopMetrics = NoopMetrics;
+/** Prometheus label syntax, with values escaped. */
+function renderLabels(labels) {
+    const entries = Object.entries(labels).sort(([left], [right]) => left.localeCompare(right));
+    if (entries.length === 0)
+        return '';
+    const rendered = entries.map(([key, value]) => `${key}="${escapeLabelValue(value)}"`);
+    return `{${rendered.join(',')}}`;
+}
+function escapeLabelValue(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+}
+//# sourceMappingURL=metrics.js.map

package/dist/observability.module.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `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.
+ */
+import { type DynamicModule } from '@nestjs/common';
+import type { ObservabilityConfig } from '@nage-api/contracts';
+import type { Clock, HealthCheck, MetricsPort, TracerPort } from './ports.js';
+export interface NageObservabilityModuleOptions {
+    readonly observability?: ObservabilityConfig;
+    /** Bind a real tracer — an OpenTelemetry adapter, say. */
+    readonly tracer?: TracerPort;
+    /** Bind a different metrics sink; the built-in registry is the default. */
+    readonly metrics?: MetricsPort;
+    /** Readiness probes contributed by the application and its drivers. */
+    readonly checks?: readonly HealthCheck[];
+    /** Per-probe timeout; a check that has not answered by then is down. */
+    readonly healthTimeoutMs?: number;
+    /** Include each failing check's message in `/health/ready`. Off by default. */
+    readonly exposeHealthDetail?: boolean;
+    readonly clock?: Clock;
+}
+export declare class NageObservabilityModule {
+    static forRoot(options?: NageObservabilityModuleOptions): DynamicModule;
+}
+//# sourceMappingURL=observability.module.d.ts.map