@objectstack/observability 17.0.0 → 17.1.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Logger } from '@objectstack/spec/contracts';
+import { IHttpServer, Logger } from '@objectstack/spec/contracts';
 export { Logger } from '@objectstack/spec/contracts';
 import { ExecutionContext } from '@objectstack/spec/kernel';
 
@@ -118,13 +118,27 @@ declare const OBSERVABILITY_ERRORS_SERVICE = "observability:errors";
  * stay in the deployment repo.
  */
 declare const SEMCONV: {
-    /** Counter, labels: `method`, `route`, `status`. */
+    /**
+     * Counter, labels: `method`, `route`, `status`. Emitted by the TRANSPORT
+     * through the `IHttpServer.afterResponse` seam (#9835), so it covers
+     * every inbound request on the server rather than only the routes the
+     * runtime dispatcher registers.
+     */
     readonly httpRequestsTotal: "http_requests_total";
-    /** Histogram (ms), labels: `method`, `route`. */
+    /**
+     * Histogram (ms), labels: `method`, `route`. Emitted by the TRANSPORT
+     * through the same seam (#9834). It measures the REQUEST as the transport
+     * sees it — first sight to the response existing, middleware chain and
+     * body parse included — not the handler's share of it.
+     */
     readonly httpRequestDurationMs: "http_request_duration_ms";
     /**
-     * Counter, labels: `method`, `route`. Incremented when an
-     * in-flight handler throws after the response is sent.
+     * Counter, labels: `method`, `route`. Incremented when an in-flight
+     * handler throws after the response is sent. Emitted by
+     * `@objectstack/runtime`'s `instrumentRouteHandler`, and NOT movable to
+     * the seam above as-is: the observation carries a status but no throw
+     * signal, so a transport-side emitter would count a different population
+     * (#9834 records the fork).
      */
     readonly httpRequestErrorsTotal: "http_request_errors_total";
     /** Counter, labels: `adapter` (`local`|`s3`|…), `op` (`get`|`put`|`delete`|`head`), `result` (`ok`|`error`). */
@@ -133,11 +147,40 @@ declare const SEMCONV: {
     readonly storageOperationDurationMs: "storage_operation_duration_ms";
     /** Counter, labels: `adapter`, `op`, `errorClass`. */
     readonly storageErrorsTotal: "storage_errors_total";
-    /** Counter, labels: `adapter` (`memory`|`redis`), `result` (`hit`|`miss`). */
+    /**
+     * Counter, labels: `adapter` (`memory`|`redis`), `result` (`hit`|`miss`).
+     *
+     * ⚠️ A flat zero means "NO CONFIGURED CONSUMER", not "no cache activity",
+     * and — unlike the HTTP families above — it is NOT an instrumentation gap.
+     * The adapters hold the host's registry and count every call they receive
+     * (#9832 wired that; #9951 pins it), so a zero here is TRUE. What it fails
+     * to communicate is WHY.
+     *
+     * The why: nothing consults the `cache` service unconditionally. Every
+     * production consumer is a rate-limit / budget counter store, and each is
+     * gated on a declaration somebody has to write — better-auth's per-IP
+     * counters (`rate_limit_max` / `rate_limit_window_seconds` in auth
+     * settings), the dispatcher's inbound limiter and its declarative
+     * per-endpoint buckets (an armed `rateLimit` budget; with none declared
+     * the dispatcher registers no limiter at all), and the per-number OTP send
+     * budget (an SMS send path). A default install declares none of them, so
+     * this counter stays at 0 while the server handles traffic normally.
+     *
+     * ⇒ Read a flat `cache_*` as a question about CONFIGURATION, never as a 0%
+     * hit rate or a broken adapter. Before trusting a cache hit-rate panel,
+     * confirm at least one consumer above is actually armed.
+     */
     readonly cacheLookupsTotal: "cache_lookups_total";
-    /** Counter, labels: `adapter`, `op` (`set`|`delete`|`clear`). */
+    /**
+     * Counter, labels: `adapter`, `op` (`set`|`delete`|`clear`). Same
+     * "zero = no configured consumer" reading as `cacheLookupsTotal` above.
+     */
     readonly cacheWritesTotal: "cache_writes_total";
-    /** Counter, labels: `adapter`, `op`, `errorClass`. */
+    /**
+     * Counter, labels: `adapter`, `op`, `errorClass`. Same "zero = no
+     * configured consumer" reading as `cacheLookupsTotal` above — a zero is
+     * "nothing was asked of the cache", not "every call succeeded".
+     */
     readonly cacheErrorsTotal: "cache_errors_total";
     /**
      * Counter, labels: `app`, `job`. Incremented when a DECLARED background
@@ -165,6 +208,101 @@ declare const RUNTIME_METRICS: {
     readonly httpRequestErrorsTotal: "http_request_errors_total";
 };
 
+/**
+ * What an `arm*` call in this module did:
+ *
+ *  - `'armed'` — the emitting observer was registered on this call.
+ *  - `'already-armed'` — some earlier caller already armed this server for
+ *    THIS metric family; the seam emits it, and this call registered nothing
+ *    (first-wins).
+ *  - `'unsupported'` — the transport does not implement the
+ *    `IHttpServer.afterResponse` seam; it reports NO HTTP metrics (#9835:
+ *    zero there means "not instrumented", never "no traffic"), and the
+ *    caller must decide how to degrade — the runtime dispatcher falls back
+ *    to instrumenting its own routes.
+ */
+type ArmHttpMetricResult = 'armed' | 'already-armed' | 'unsupported';
+/**
+ * The name {@link armHttpRequestCounter} shipped with. Kept as an alias
+ * rather than renamed: the export is already in the pending release, and the
+ * two families arm through separate entry points anyway.
+ */
+type ArmHttpRequestCounterResult = ArmHttpMetricResult;
+/**
+ * Arm `http_requests_total{method,route,status}` on a transport through the
+ * `IHttpServer.afterResponse` observation seam (#9835) — AT MOST ONCE per
+ * server, whoever calls first.
+ *
+ * ## Why arming is centralized here
+ *
+ * The contract's ownership rule says a request must never be double-counted,
+ * and two composition layers legitimately hold both a server and a metrics
+ * registry: the transport's own hosting plugin (`HonoServerPlugin`, which
+ * the 2026-08-18 ruling on #9650 made the counter's home) and the runtime
+ * dispatcher (whose `observability.metrics` config is the wiring the docs
+ * demonstrate). When a host hands ONE registry to both — the ordinary case —
+ * two independently-registered observers would land every request on the
+ * same series twice: exactly the #9833 distortion, rebuilt one seam over.
+ * Routing every arming through this function makes "exactly one
+ * counter-emitting observer per server" structural: the first caller arms
+ * (in the shipped composition that is the transport plugin, in Phase 1),
+ * every later caller is told the seam already counts.
+ *
+ * The label shape is pinned by the contract: `route` is the transport's
+ * `routePattern` — the registered PATTERN, never the concrete path — and
+ * `status` is stringified for the label set. Emission goes through the
+ * transport's observer-isolation guarantee, so a throwing registry cannot
+ * break a response.
+ *
+ * @param server - The transport. Pass the RAW registered `http.server`
+ *   instance, not a wrapper: the latch is per object identity, and a wrapper
+ *   would both fork the latch and (per #5122) risk erasing the optional
+ *   member this function feature-detects.
+ * @param metrics - The registry the counter lands in. First caller wins; a
+ *   second registry offered later is NOT added (the contract's one-owner
+ *   rule), and the result says so.
+ */
+declare function armHttpRequestCounter(server: IHttpServer, metrics: MetricsRegistry): ArmHttpMetricResult;
+/**
+ * Arm `http_request_duration_ms{method,route}` on a transport through the
+ * `IHttpServer.afterResponse` observation seam — AT MOST ONCE per server,
+ * whoever calls first. The duration half of #9834, built on the mechanism
+ * #9835 proved out for `http_requests_total`.
+ *
+ * ## Why the histogram has to move too
+ *
+ * #9835 moved only the counter, which left the docs' two derived signals
+ * inconsistent with each other: 5xx rate saw every inbound surface while p95
+ * latency still saw the dispatcher's own routes. An operator reading one
+ * dashboard got request volume for `/api/v1/*` beside a latency panel with no
+ * series for it — and the worse reading is the p95 that IS drawn, computed
+ * from dispatcher routes only and presented as the server's.
+ *
+ * ## ⚠️ The observation WINDOW changes with the emitter
+ *
+ * The dispatcher's per-route wrapper timed `await handler(req, res)` — handler
+ * latency. This seam times the transport's own `use('*')` around
+ * `await next()`, which is what {@link HttpResponseObservation.elapsedMs}
+ * means: "from the transport first seeing the request to the response
+ * existing". That includes the middleware chain and body parse, so the series
+ * can only move UP, never down. It is the number an operator's latency panel
+ * should have been showing — the request's latency rather than one layer's
+ * share of it — but it is a visible change in an existing series, so it is
+ * stated here, in the changeset, and in `docs/OBSERVABILITY.md` rather than
+ * left for a dashboard to discover.
+ *
+ * The label set is unchanged and stays the SEMCONV-declared `{method,route}`:
+ * `route` is the transport's `routePattern` (the registered PATTERN, never the
+ * concrete path), and no `status` label is added — a histogram split by status
+ * is a different series shape than the one the docs tell operators to graph.
+ *
+ * @param server - The transport. Pass the RAW registered `http.server`
+ *   instance, not a wrapper — the latch is per object identity, and (per
+ *   #5122) a wrapper risks erasing the optional member this feature-detects.
+ * @param metrics - The registry the histogram lands in. First caller wins.
+ */
+declare function armHttpRequestDurationHistogram(server: IHttpServer, metrics: MetricsRegistry): ArmHttpMetricResult;
+
 /**
  * No-op metrics registry — the default. Discards every observation.
  * Production deployments should swap this for a real registry; tests
@@ -617,4 +755,4 @@ declare function isPerfDisclosurePrivileged(): boolean;
  */
 declare function isPerfDisclosurePrincipal(ec: ExecutionContext | undefined): boolean;
 
-export { type CapturedError, ConsoleErrorReporter, ConsoleLogger, ConsoleMetricsRegistry, type ErrorReporter, InMemoryErrorReporter, InMemoryMetricsRegistry, JsonLogger, LOG_LEVELS, type LogLevel, type MetricSample, type MetricsRegistry, NoopErrorReporter, NoopLogger, NoopMetricsRegistry, OBSERVABILITY_ERRORS_SERVICE, OBSERVABILITY_METRICS_SERVICE, type OtlpHttpExporterOptions, OtlpHttpMetricsRegistry, type PerfDisclosureGate, PerfTiming, RUNTIME_METRICS, SEMCONV, type ServerTimingDetail, type ServerTimingMark, allowPerfDisclosure, countServerTiming, currentPerfTiming, formatServerTiming, isPerfDisclosureAllowed, isPerfDisclosurePrincipal, isPerfDisclosurePrivileged, measureServerTiming, perfNow, recordServerTiming, recordServerTimingDetail, runWithPerfDisclosure, runWithPerfTiming, startServerTiming };
+export { type ArmHttpMetricResult, type ArmHttpRequestCounterResult, type CapturedError, ConsoleErrorReporter, ConsoleLogger, ConsoleMetricsRegistry, type ErrorReporter, InMemoryErrorReporter, InMemoryMetricsRegistry, JsonLogger, LOG_LEVELS, type LogLevel, type MetricSample, type MetricsRegistry, NoopErrorReporter, NoopLogger, NoopMetricsRegistry, OBSERVABILITY_ERRORS_SERVICE, OBSERVABILITY_METRICS_SERVICE, type OtlpHttpExporterOptions, OtlpHttpMetricsRegistry, type PerfDisclosureGate, PerfTiming, RUNTIME_METRICS, SEMCONV, type ServerTimingDetail, type ServerTimingMark, allowPerfDisclosure, armHttpRequestCounter, armHttpRequestDurationHistogram, countServerTiming, currentPerfTiming, formatServerTiming, isPerfDisclosureAllowed, isPerfDisclosurePrincipal, isPerfDisclosurePrivileged, measureServerTiming, perfNow, recordServerTiming, recordServerTimingDetail, runWithPerfDisclosure, runWithPerfTiming, startServerTiming };

package/dist/index.js

@@ -4,14 +4,28 @@ var OBSERVABILITY_ERRORS_SERVICE = "observability:errors";
 
 // src/semconv.ts
 var SEMCONV = {
-  // ── HTTP — emitted by `@objectstack/runtime`'s instrumentRouteHandler ──
-  /** Counter, labels: `method`, `route`, `status`. */
+  // ── HTTP — emitter differs per family, see each ────────────────────
+  /**
+   * Counter, labels: `method`, `route`, `status`. Emitted by the TRANSPORT
+   * through the `IHttpServer.afterResponse` seam (#9835), so it covers
+   * every inbound request on the server rather than only the routes the
+   * runtime dispatcher registers.
+   */
   httpRequestsTotal: "http_requests_total",
-  /** Histogram (ms), labels: `method`, `route`. */
+  /**
+   * Histogram (ms), labels: `method`, `route`. Emitted by the TRANSPORT
+   * through the same seam (#9834). It measures the REQUEST as the transport
+   * sees it — first sight to the response existing, middleware chain and
+   * body parse included — not the handler's share of it.
+   */
   httpRequestDurationMs: "http_request_duration_ms",
   /**
-   * Counter, labels: `method`, `route`. Incremented when an
-   * in-flight handler throws after the response is sent.
+   * Counter, labels: `method`, `route`. Incremented when an in-flight
+   * handler throws after the response is sent. Emitted by
+   * `@objectstack/runtime`'s `instrumentRouteHandler`, and NOT movable to
+   * the seam above as-is: the observation carries a status but no throw
+   * signal, so a transport-side emitter would count a different population
+   * (#9834 records the fork).
    */
   httpRequestErrorsTotal: "http_request_errors_total",
   // ── Storage — emitted by `@objectstack/service-storage` adapters ──
@@ -22,11 +36,41 @@ var SEMCONV = {
   /** Counter, labels: `adapter`, `op`, `errorClass`. */
   storageErrorsTotal: "storage_errors_total",
   // ── Cache — emitted by `@objectstack/service-cache` adapters ──
-  /** Counter, labels: `adapter` (`memory`|`redis`), `result` (`hit`|`miss`). */
+  // Uniform emitter; what varies is who CONSULTS the service — see below.
+  /**
+   * Counter, labels: `adapter` (`memory`|`redis`), `result` (`hit`|`miss`).
+   *
+   * ⚠️ A flat zero means "NO CONFIGURED CONSUMER", not "no cache activity",
+   * and — unlike the HTTP families above — it is NOT an instrumentation gap.
+   * The adapters hold the host's registry and count every call they receive
+   * (#9832 wired that; #9951 pins it), so a zero here is TRUE. What it fails
+   * to communicate is WHY.
+   *
+   * The why: nothing consults the `cache` service unconditionally. Every
+   * production consumer is a rate-limit / budget counter store, and each is
+   * gated on a declaration somebody has to write — better-auth's per-IP
+   * counters (`rate_limit_max` / `rate_limit_window_seconds` in auth
+   * settings), the dispatcher's inbound limiter and its declarative
+   * per-endpoint buckets (an armed `rateLimit` budget; with none declared
+   * the dispatcher registers no limiter at all), and the per-number OTP send
+   * budget (an SMS send path). A default install declares none of them, so
+   * this counter stays at 0 while the server handles traffic normally.
+   *
+   * ⇒ Read a flat `cache_*` as a question about CONFIGURATION, never as a 0%
+   * hit rate or a broken adapter. Before trusting a cache hit-rate panel,
+   * confirm at least one consumer above is actually armed.
+   */
   cacheLookupsTotal: "cache_lookups_total",
-  /** Counter, labels: `adapter`, `op` (`set`|`delete`|`clear`). */
+  /**
+   * Counter, labels: `adapter`, `op` (`set`|`delete`|`clear`). Same
+   * "zero = no configured consumer" reading as `cacheLookupsTotal` above.
+   */
   cacheWritesTotal: "cache_writes_total",
-  /** Counter, labels: `adapter`, `op`, `errorClass`. */
+  /**
+   * Counter, labels: `adapter`, `op`, `errorClass`. Same "zero = no
+   * configured consumer" reading as `cacheLookupsTotal` above — a zero is
+   * "nothing was asked of the cache", not "every call succeeded".
+   */
   cacheErrorsTotal: "cache_errors_total",
   // ── Background jobs — emitted by `@objectstack/runtime`'s AppPlugin ──
   /**
@@ -50,6 +94,42 @@ var RUNTIME_METRICS = {
   httpRequestErrorsTotal: SEMCONV.httpRequestErrorsTotal
 };
 
+// src/http-transport-metrics.ts
+var HTTP_REQUEST_COUNTER_ARMED = /* @__PURE__ */ Symbol.for(
+  "objectstack.observability.httpRequestCounterArmed"
+);
+function armHttpRequestCounter(server, metrics) {
+  if (typeof server.afterResponse !== "function") return "unsupported";
+  const latched = server;
+  if (latched[HTTP_REQUEST_COUNTER_ARMED]) return "already-armed";
+  latched[HTTP_REQUEST_COUNTER_ARMED] = true;
+  server.afterResponse((observation) => {
+    metrics.counter(RUNTIME_METRICS.httpRequestsTotal, {
+      method: observation.method,
+      route: observation.routePattern,
+      status: String(observation.status)
+    });
+  });
+  return "armed";
+}
+var HTTP_REQUEST_DURATION_ARMED = /* @__PURE__ */ Symbol.for(
+  "objectstack.observability.httpRequestDurationArmed"
+);
+function armHttpRequestDurationHistogram(server, metrics) {
+  if (typeof server.afterResponse !== "function") return "unsupported";
+  const latched = server;
+  if (latched[HTTP_REQUEST_DURATION_ARMED]) return "already-armed";
+  latched[HTTP_REQUEST_DURATION_ARMED] = true;
+  server.afterResponse((observation) => {
+    metrics.histogram(
+      RUNTIME_METRICS.httpRequestDurationMs,
+      observation.elapsedMs,
+      { method: observation.method, route: observation.routePattern }
+    );
+  });
+  return "armed";
+}
+
 // src/metrics-exporters.ts
 var NoopMetricsRegistry = class {
   counter() {
@@ -648,6 +728,8 @@ export {
   RUNTIME_METRICS,
   SEMCONV,
   allowPerfDisclosure,
+  armHttpRequestCounter,
+  armHttpRequestDurationHistogram,
   countServerTiming,
   currentPerfTiming,
   formatServerTiming,