@daloyjs/core 1.1.0 → 1.2.0

package/README.md

@@ -584,7 +584,7 @@ The core only ever sees `Request → Response`. Adapters live at the edge.
 
 ## Status
 
-DaloyJS is at **`1.1.0`** — the public API is frozen and follows SemVer from here: no `1.x` minor changes the API, and any deprecation gets at least one minor cycle before removal. `@daloyjs/core` (npm), `create-daloy` (npm), and [`@daloyjs/daloy`](https://jsr.io/@daloyjs/daloy) (JSR) ship together at matching versions.
+DaloyJS is at **`1.1.1`** — the public API is frozen and follows SemVer from here: no `1.x` minor changes the API, and any deprecation gets at least one minor cycle before removal. `@daloyjs/core` (npm), `create-daloy` (npm), and [`@daloyjs/daloy`](https://jsr.io/@daloyjs/daloy) (JSR) ship together at matching versions.
 
 The release-candidate train that led here was largely adversarial: `rc.1` through `rc.9` carried remediations from live over-the-wire engagements against realistic multi-tenant apps, and the findings clustered in one place worth naming — **composition**, not individual modules. A `responseCache()` mounted ahead of the network-identity gates silently disabled them; the same order left `rateLimit()` never counting the requests a cache hit or an idempotent replay served; a forwarded-header resolver read the one `X-Forwarded-For` slot an attacker controls; `idempotency()` replayed a stored `Set-Cookie`. Each is fixed, each has a regression test, and several are now refuse-to-boot guards so the unsafe wiring cannot ship quietly. See the [CHANGELOG](CHANGELOG.md) for the full train and [boot guards](https://daloyjs.dev/docs/security/boot-guards) for the orders the framework now refuses.
 
@@ -666,6 +666,7 @@ The framework refuses to start (or to construct) when configuration is unsafe:
 - `paginationQuery()` / `encodeCursor()` / `decodeCursor()` / `buildPageLinks()` / `buildLinkHeader()` cursor-pagination helpers at `@daloyjs/core/pagination`: opaque base64url cursors (length-capped, prototype-pollution-safe decode → `400` on tamper), RFC 8288 `Link` header emission with CRLF / header-injection guards, and a Standard Schema that validates `cursor`/`limit` and auto-wires both into the OpenAPI spec + typed client via `toJSONSchema()`.
 - `app.metrics()` + `MetricsRegistry` / `httpMetrics()` Prometheus / OpenMetrics exposition at `@daloyjs/core/metrics`: dependency-free counters / gauges / histograms, RED instrumentation (`http_requests_total`, `http_request_duration_seconds`, `http_requests_in_flight`) plus process gauges, exposition-injection-safe name/label validation, a per-metric cardinality cap, and an opt-in `/metrics` route with the same hardened posture as `app.healthcheck()` (bearer token + `timingSafeEqual`, per-IP rate limit, refuse-to-boot unauthenticated in production). The repo ships an `examples/observability/` Docker Compose stack that starts a pre-configured Prometheus + Grafana pair (with an auto-provisioned RED + heatmap dashboard) against any local app via `docker compose -f examples/observability/docker-compose.yml up`.
 - `otelTracing()` OpenTelemetry-compatible distributed tracing at `@daloyjs/core/tracing`: a dependency-free `Hooks` bundle that opens one `SERVER` span per request, attaches HTTP semantic-convention attributes (`http.request.method`, `url.path`, `server.address` / `server.port`, `http.response.status_code`, …), records exceptions + escalates `5xx` to `ERROR`, guarantees a single `span.end()`, and exposes the live span on `ctx.state.otelSpan`. Bring any tracer matching the small `TracingTracer` interface (the real `@opentelemetry/api` SDK on Node, or a custom exporter on Workers/Deno) plus your own propagator via `contextFromRequest` for `traceparent` continuation — no OTel SDK is forced into your install. The `examples/observability/` stack also runs **Jaeger**, and `examples/otel-tracing-demo.ts` ships a ~120-line dependency-free OTLP/HTTP exporter that streams spans straight to it.
+- `new App({ telemetry: true })` native OpenTelemetry OTLP push export at `@daloyjs/core/otlp`: one flag tees the app logger to the collector as OTLP logs and records `http.server.request.duration` per the OTel HTTP semantic conventions (spec attributes incl. `http.route` from the matched route template via the new `ctx.routePath`, spec bucket boundaries), pushed as dependency-free OTLP/HTTP JSON to the endpoint in the standard `OTEL_EXPORTER_OTLP_*` env vars — zero config on collector-based platforms that inject them, silent no-op without them. Standalone `createOtlpLogExporter()` / `createOtlpMetricsExporter()` (cumulative temporality — totals survive failed pushes) / `semconvHttpMetrics()` exports; fail-safe by contract (bounded queues, series-cardinality cap, a dead collector never affects serving, tenant-routing header values never logged).
 - `tenancy()` secure-by-default multitenancy at `@daloyjs/core/tenancy`: a dependency-free `Hooks` bundle that resolves the calling tenant once per request and exposes it on `ctx.state.tenant`. Pluggable resolution (`tenantFromSubdomain` PSL-aware, `tenantFromHeader`, `tenantFromPathPrefix`, `tenantFromClaim`, or a custom `(ctx) => string`, tried in array order). **Refuse-unresolved by default** (no ambient "default" tenant leak), **format-validated ids** (rejects key/log-injection + cache-poisoning payloads before they reach a key), **no-enumeration `404`** for unknown tenants, and **host-spoof-safe** subdomain resolution. A `tenantScope()` key helper drops straight into `rateLimit` `keyGenerator` and `concurrencyLimit` / `idempotency` `scope` to partition each per tenant (CWE-524 cross-tenant cache defense); `responseCache()` needs no wiring at all — it reads the resolved tenant itself and refuses to boot if mounted ahead of `tenancy()`. Runnable `examples/multitenancy-demo.ts`.
 - `resilientFetch()` + `CircuitBreaker` outbound resilience at `@daloyjs/core/fetch-resilience`: a dependency-free circuit breaker (`closed → open → half-open`), retry-with-backoff (exponential + full jitter, idempotent-method/transient-status scoped, honours `Retry-After`), and a per-call timeout (`AbortController` → `FetchTimeoutError`) designed to layer **on top of** `fetchGuard()` — an `SsrfBlockedError` is a terminal refusal that is never retried and never trips the breaker, so SSRF protection stays intact under the resilience layer.
 - `createWebhookSender()` + `MemoryWebhookDeadLetterSink` outbound webhook delivery at `@daloyjs/core/webhook-delivery`: the outbound counterpart to `verifyWebhookSignature()` — timestamped HMAC-signed `POST`s (`webhook-id` / `webhook-timestamp` / `webhook-signature`, computed over `"<timestamp>.<body>"` and reused across retries for safe deduping), bounded retry-with-backoff (transient-status + network scoped, honours `Retry-After`), per-attempt timeout, and dead-letter semantics. Transport defaults to `fetchGuard()`, so a subscriber URL pointing at cloud metadata or a private range is refused with a terminal `SsrfBlockedError` (never retried, dead-lettered once). Zero runtime dependencies.

package/dist/app.d.ts

@@ -1,5 +1,6 @@
 import { WebSocketRegistry, type WebSocketHandler } from "./websocket.js";
 import { type Logger } from "./logger.js";
+import { type AppTelemetry, type TelemetryOptions } from "./otlp.js";
 import type { HttpMethod, Hooks, PathString, RequestSchemas, ResponsesMap, RouteDefinition } from "./types.js";
 import { type OpenAPIInfo, type OpenAPIOptions } from "./openapi.js";
 import { type DocsAssetOptions, type DocsAuthLauncherOptions, type DocsContentSecurityPolicyOptions, type RedocConfiguration, type ScalarJsonValue, type ScalarReferenceConfiguration, type SwaggerUiConfiguration } from "./docs.js";
@@ -74,6 +75,18 @@ export interface AppOptions {
     preset?: SecurityPreset;
     /** Validate handler responses against declared response schemas. Default: true. */
     validateResponses?: boolean;
+    /**
+     * OpenTelemetry OTLP push export. `true` (or an options object) exports the
+     * app logger's output as OTLP logs and records `http.server.request.duration`
+     * per the OTel HTTP semantic conventions, pushed to the collector named by
+     * the standard `OTEL_EXPORTER_OTLP_*` environment variables. A silent no-op
+     * when no endpoint is configured, so it is safe to keep enabled in
+     * development. Export failures never affect request serving. See
+     * {@link TelemetryOptions}.
+     *
+     * @since 1.2.0
+     */
+    telemetry?: boolean | TelemetryOptions;
     /** Hard cap on request body size in bytes. Default: 1 MiB. */
     bodyLimitBytes?: number;
     /** Reject requests whose Content-Type isn't in this allowlist (when a body schema is declared). */
@@ -934,6 +947,13 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
     readonly options: Required<Pick<AppOptions, "validateResponses" | "bodyLimitBytes" | "requestTimeoutMs">> & AppOptions;
     /** Structured logger for the app. Defaults to a JSON-lines console logger; override via `options.logger`. */
     readonly log: Logger;
+    /**
+     * OTLP telemetry wiring created by the `telemetry` option; `undefined` when
+     * the option is off. Exposed for tests and advanced flushing.
+     *
+     * @since 1.2.0
+     */
+    readonly telemetry?: AppTelemetry;
     /**
      * Public registry: enables OpenAPI gen, typed-client gen, dead-route detection.
      *

package/dist/app.js

@@ -3,6 +3,7 @@ import { WebSocketRegistry, normalizeWebSocketOptions, } from "./websocket.js";
 import { BadRequestError, ForbiddenError, HttpError, InternalError, MethodNotAllowedError, NotFoundError, PayloadTooLargeError, RequestTimeoutError, TooManyRequestsError, UnsupportedMediaTypeError, ValidationError, } from "./errors.js";
 import { readBodyLimited, safeJsonParseLimited, randomId, assertInboundHeaderGuards, DEFAULT_MAX_HEADER_COUNT, assertStrongSecret, timingSafeEqual, isForbiddenObjectKey, } from "./security.js";
 import { createLogger, noopLogger, sanitizeUrlForLog } from "./logger.js";
+import { createAppTelemetry } from "./otlp.js";
 import { generateOpenAPI, openapiToYAML, } from "./openapi.js";
 import { isSchemaValidatedResponse } from "./internal-response.js";
 import { asyncapiHtml, docsContentSecurityPolicy, redocHtml, scalarHtml, swaggerUiHtml, } from "./docs.js";
@@ -374,6 +375,13 @@ export class App {
     options;
     /** Structured logger for the app. Defaults to a JSON-lines console logger; override via `options.logger`. */
     log;
+    /**
+     * OTLP telemetry wiring created by the `telemetry` option; `undefined` when
+     * the option is off. Exposed for tests and advanced flushing.
+     *
+     * @since 1.2.0
+     */
+    telemetry;
     /**
      * Public registry: enables OpenAPI gen, typed-client gen, dead-route detection.
      *
@@ -505,12 +513,23 @@ export class App {
             jsonMaxDepth: resolved.jsonMaxDepth ?? DEFAULTS.jsonMaxDepth,
             ...resolved,
         };
+        // Telemetry is resolved before the logger so the logger's write sink can
+        // tee into the OTLP log exporter. Inert when no endpoint is configured.
+        const telemetryOpt = options.telemetry;
+        this.telemetry =
+            telemetryOpt === undefined || telemetryOpt === false
+                ? undefined
+                : createAppTelemetry(telemetryOpt === true ? {} : telemetryOpt);
+        const telemetryWrite = this.telemetry?.logWrite;
         this.log =
             options.logger === false
                 ? noopLogger
                 : options.logger && typeof options.logger.info === "function"
                     ? options.logger
-                    : createLogger({ level: options.logger?.level ?? "info" });
+                    : createLogger({
+                        level: options.logger?.level ?? "info",
+                        ...(telemetryWrite !== undefined ? { write: telemetryWrite } : {}),
+                    });
         this.warnOnEnvMismatch();
         this.assertDisconnectStatusCode();
         assertBehindProxy(this.options.behindProxy);
@@ -522,6 +541,20 @@ export class App {
         this.maybeInstallCrashHandlers();
         this.maybeMountDocs();
         this.maybeMountAsyncAPI();
+        if (this.telemetry !== undefined) {
+            if (this.telemetry.hooks !== undefined)
+                this.use(this.telemetry.hooks);
+            const telemetry = this.telemetry;
+            this.onClose(() => telemetry.flush());
+            this.log.info({
+                event: "telemetry.otlp",
+                active: telemetry.endpoint !== null,
+                // Endpoint only — OTLP headers may carry tenant credentials.
+                endpoint: telemetry.endpoint ?? undefined,
+            }, telemetry.endpoint !== null
+                ? "OTLP telemetry export active"
+                : "Telemetry enabled but no OTEL_EXPORTER_OTLP_ENDPOINT configured; export disabled");
+        }
     }
     /**
      * Validate {@link AppOptions.disconnectStatusCode}.
@@ -2683,6 +2716,8 @@ export class App {
             // perimeter hooks can reject unauthenticated callers without consuming
             // an attacker-controlled request stream.
             ctx = createPreBodyContext(request, getUrl, match.params);
+            // Matched route template for low-cardinality labels (`http.route`).
+            ctx.routePath = def.path;
             // Stable two-field write keeps `ctx.state`'s hidden class consistent across
             // requests for the common no-decorator case. The decorations spread only
             // fires when `app.decorate()` was actually called.
@@ -3502,21 +3537,21 @@ function finalizeResponse(res, ctx, hooks, stripFingerprint = true) {
             return sentResult.then((sent) => {
                 if (sent instanceof Response)
                     final = sent;
-                return finishFinalize(final, hooks, stripFingerprint);
+                return finishFinalize(final, ctx, hooks, stripFingerprint);
             });
         }
         if (sentResult instanceof Response)
             final = sentResult;
     }
-    return finishFinalize(final, hooks, stripFingerprint);
+    return finishFinalize(final, ctx, hooks, stripFingerprint);
 }
-function finishFinalize(res, hooks, stripFingerprint) {
+function finishFinalize(res, ctx, hooks, stripFingerprint) {
     if (stripFingerprint) {
         res.headers.delete("server");
         res.headers.delete("x-powered-by");
     }
     if (hooks.onResponse !== undefined) {
-        const onResponseResult = hooks.onResponse(res);
+        const onResponseResult = hooks.onResponse(res, ctx);
         if (isPromiseLike(onResponseResult)) {
             return onResponseResult.then(() => res);
         }
@@ -3703,6 +3738,7 @@ class RequestContext {
     body = undefined;
     state;
     set;
+    routePath = undefined;
     _q = undefined;
     _qBuilder = undefined;
     _qSet = false;

package/dist/index.d.ts

@@ -95,6 +95,8 @@ export { encodeCursor, decodeCursor, buildLinkHeader, buildPageLinks, pagination
 export type { PaginationLink, PageLinkOptions, PageLinks, PaginationQueryOptions, PaginationParams, PaginationQuerySchema, } from "./pagination.js";
 export { MetricsRegistry, Counter, Gauge, Histogram, httpMetrics, DEFAULT_DURATION_BUCKETS, PROMETHEUS_CONTENT_TYPE, } from "./metrics.js";
 export type { MetricLabels, MetricsRegistryOptions, HttpMetricsOptions } from "./metrics.js";
+export { createOtlpLogExporter, createOtlpMetricsExporter, createAppTelemetry, semconvHttpMetrics, HTTP_SERVER_REQUEST_DURATION_BUCKETS, } from "./otlp.js";
+export type { OtlpExporterOptions, OtlpLogExporter, OtlpMetricsExporter, OtlpHistogramOptions, SemconvHttpMetricsOptions, TelemetryOptions, AppTelemetry, } from "./otlp.js";
 export { fileField, multipartObject, isFileFieldSchema, isMultipartObjectSchema, } from "./multipart.js";
 export type { FileFieldSchema, FileFieldOptions, FileMagicBytesOption, FileMagicBytesSignature, MultipartObjectOptions, MultipartShape, UploadedFile, } from "./multipart.js";
 export { otelTracing, TRACING_SPAN_KIND_SERVER, TRACING_SPAN_STATUS_UNSET, TRACING_SPAN_STATUS_OK, TRACING_SPAN_STATUS_ERROR, } from "./tracing.js";

package/dist/index.js

@@ -48,6 +48,7 @@ export { idempotency, MemoryIdempotencyStore, _resetSharedIdempotencyStoresForTe
 export { responseCache, MemoryResponseCacheStore, RESPONSE_CACHE_HOOK_MARKER, _resetSharedResponseCacheStoresForTests, } from "./response-cache.js";
 export { encodeCursor, decodeCursor, buildLinkHeader, buildPageLinks, paginationQuery, MAX_CURSOR_LENGTH, } from "./pagination.js";
 export { MetricsRegistry, Counter, Gauge, Histogram, httpMetrics, DEFAULT_DURATION_BUCKETS, PROMETHEUS_CONTENT_TYPE, } from "./metrics.js";
+export { createOtlpLogExporter, createOtlpMetricsExporter, createAppTelemetry, semconvHttpMetrics, HTTP_SERVER_REQUEST_DURATION_BUCKETS, } from "./otlp.js";
 export { fileField, multipartObject, isFileFieldSchema, isMultipartObjectSchema, } from "./multipart.js";
 export { otelTracing, TRACING_SPAN_KIND_SERVER, TRACING_SPAN_STATUS_UNSET, TRACING_SPAN_STATUS_OK, TRACING_SPAN_STATUS_ERROR, } from "./tracing.js";
 export { tenancy, tenantScope, tenantFromSubdomain, tenantFromHeader, tenantFromPathPrefix, tenantFromClaim, defaultTenantNormalize, TENANCY_HOOK_MARKER, TENANCY_RESOLVED_MARKER, TENANT_UNRESOLVED, } from "./tenancy.js";

package/dist/metrics.js

@@ -401,6 +401,10 @@ export function httpMetrics(opts) {
     const routeLabel = (ctx) => {
         if (opts.route)
             return opts.route(ctx) ?? "<unknown>";
+        // The router stamps the matched route template on the context; it is
+        // low-cardinality by construction, so no cap bookkeeping is needed.
+        if (typeof ctx.routePath === "string")
+            return ctx.routePath;
         let path = "/";
         try {
             path = new URL(ctx.request.url).pathname;

package/dist/otlp.d.ts

@@ -0,0 +1,242 @@
+/**
+ * OpenTelemetry OTLP push export — logs, metrics, and semantic-convention
+ * HTTP server instrumentation, with zero runtime dependencies.
+ *
+ * Many container platforms run an in-cluster OTel collector and expect
+ * workloads to **push** telemetry: they inject the standard
+ * `OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_EXPORTER_OTLP_HEADERS` /
+ * `OTEL_RESOURCE_ATTRIBUTES` / `OTEL_SERVICE_NAME` variables into every
+ * container and scrape nothing — not stdout, not a `/metrics` route. The
+ * OTel Node SDK covers that with monkey-patching auto-instrumentation, but
+ * its ESM loader hooks are fragile on modern Node and unavailable on edge
+ * runtimes. This module is the framework-native alternative:
+ *
+ * - {@link createOtlpLogExporter} — batched OTLP/HTTP JSON log export;
+ *   tee your logger's `write` sink into it.
+ * - {@link createOtlpMetricsExporter} — cumulative counters + histograms
+ *   pushed as OTLP/HTTP JSON.
+ * - {@link semconvHttpMetrics} — a `Hooks` bundle emitting
+ *   `http.server.request.duration` exactly per the OTel HTTP semantic
+ *   conventions (names, attributes, bucket boundaries), so standard Grafana
+ *   dashboards work unchanged.
+ * - `new App({ telemetry: true })` wires all of the above automatically
+ *   (see {@link TelemetryOptions}).
+ *
+ * Everything is transport-portable (`fetch` + web-standard primitives) and
+ * **fail-safe by contract**: a dead or misconfigured collector never affects
+ * request serving — bounded queues, dropped-batch counters, no retry storms,
+ * and cumulative metric temporality so totals survive failed pushes.
+ *
+ * @module
+ * @since 1.2.0
+ */
+import type { Hooks } from "./types.js";
+/**
+ * Shared configuration for {@link createOtlpLogExporter} and
+ * {@link createOtlpMetricsExporter}. Every field falls back to the standard
+ * `OTEL_*` environment variables, so on platforms that inject them no
+ * explicit configuration is needed at all.
+ *
+ * @since 1.2.0
+ */
+export interface OtlpExporterOptions {
+    /**
+     * Collector base URL. Defaults to `OTEL_EXPORTER_OTLP_ENDPOINT`. The
+     * conventional injected value is the gRPC form (`http://host:4317`); a
+     * trailing `:4317` is rewritten to `:4318`, the collector's OTLP/HTTP port.
+     * The signal path (`/v1/logs`, `/v1/metrics`) is appended automatically.
+     */
+    endpoint?: string;
+    /**
+     * Extra request headers. Defaults to `OTEL_EXPORTER_OTLP_HEADERS`
+     * (`key=value,key2=value2`). Multi-tenant collectors route on these
+     * (e.g. `tenant_id=...`), so treat the values as credentials: DaloyJS
+     * never logs them and never includes them in errors.
+     */
+    headers?: Record<string, string>;
+    /**
+     * OTLP resource attributes. Defaults to `OTEL_RESOURCE_ATTRIBUTES`
+     * (`key=value,...`) plus `service.name` from `OTEL_SERVICE_NAME` when not
+     * already present.
+     */
+    resourceAttributes?: Record<string, string>;
+    /**
+     * Flush cadence in ms on runtimes with timers (`unref`'d — never keeps the
+     * process alive). Defaults: 5000 (logs), 15000 (metrics). Set `0` to
+     * disable the timer and flush manually / on shutdown only.
+     */
+    flushIntervalMs?: number;
+    /** Injectable transport for tests. Default `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * Batched OTLP/HTTP JSON **log** exporter returned by
+ * {@link createOtlpLogExporter}.
+ *
+ * @since 1.2.0
+ */
+export interface OtlpLogExporter {
+    /**
+     * Queue one log line (no trailing newline). JSON lines are decomposed:
+     * `msg`/`message`/`event` becomes the record body, `level` maps to the
+     * OTLP severity, and every remaining field ships as a string attribute
+     * (surfacing as structured metadata in Loki-style backends). Non-JSON
+     * lines ship verbatim as the body.
+     */
+    pushLine(line: string): void;
+    /** Push pending records now. Never rejects; failures count as drops. */
+    flush(): Promise<void>;
+    /** Batches dropped because the queue overflowed or the collector errored. */
+    readonly droppedBatches: number;
+}
+/**
+ * Histogram configuration for {@link OtlpMetricsExporter.record}.
+ *
+ * @since 1.2.0
+ */
+export interface OtlpHistogramOptions {
+    /** UCUM unit, e.g. `"s"` or `"{token}"`. */
+    unit: string;
+    /** Explicit bucket upper bounds, ascending. */
+    boundaries: readonly number[];
+}
+/**
+ * Cumulative OTLP/HTTP JSON **metrics** exporter returned by
+ * {@link createOtlpMetricsExporter}. Counters and histograms use cumulative
+ * temporality, so a failed push is self-healing: the totals are retained and
+ * the next successful push carries them.
+ *
+ * @since 1.2.0
+ */
+export interface OtlpMetricsExporter {
+    /** Add `value` (default `1`, must be finite and non-negative) to the counter series `name` + `attributes`. */
+    count(name: string, attributes: Record<string, string>, value?: number): void;
+    /** Record one observation into the histogram series `name` + `attributes`. */
+    record(name: string, attributes: Record<string, string>, value: number, options: OtlpHistogramOptions): void;
+    /** Push the current state now. Never rejects; failures count as drops. */
+    flush(): Promise<void>;
+    /** Pushes dropped because the collector rejected/errored, plus series dropped at the cardinality cap. */
+    readonly droppedBatches: number;
+}
+/**
+ * Spec-defined default bucket boundaries for `http.server.request.duration`,
+ * in seconds (OTel HTTP semantic conventions).
+ *
+ * @since 1.2.0
+ */
+export declare const HTTP_SERVER_REQUEST_DURATION_BUCKETS: readonly number[];
+/**
+ * Create a batched OTLP/HTTP JSON log exporter, or `null` when no endpoint is
+ * configured (local development, tests) so callers can no-op cheaply.
+ *
+ * Fail-safe by contract: {@link OtlpLogExporter.flush} never rejects, a dead
+ * collector cannot grow the queue past its cap (oldest records are dropped
+ * and counted), and export work is decoupled from request handling.
+ *
+ * @param opts - Endpoint/header/resource overrides; defaults from `OTEL_*` env vars.
+ * @returns The exporter, or `null` when no endpoint is configured.
+ * @since 1.2.0
+ */
+export declare function createOtlpLogExporter(opts?: OtlpExporterOptions): OtlpLogExporter | null;
+/**
+ * Create a cumulative OTLP/HTTP JSON metrics exporter, or `null` when no
+ * endpoint is configured.
+ *
+ * Counters export as monotonic cumulative sums and histograms as cumulative
+ * explicit-bounds histograms, so state survives failed pushes (the next
+ * successful push carries the accumulated totals). Total series are capped
+ * ({@link OtlpMetricsExporter.droppedBatches} counts series refused at the
+ * cap) and attribute values are length-truncated — both cardinality guards
+ * against hostile or buggy attribute sources.
+ *
+ * @param opts - Endpoint/header/resource overrides; defaults from `OTEL_*` env vars.
+ * @returns The exporter, or `null` when no endpoint is configured.
+ * @since 1.2.0
+ */
+export declare function createOtlpMetricsExporter(opts?: OtlpExporterOptions): OtlpMetricsExporter | null;
+/** Options for {@link semconvHttpMetrics}. */
+export interface SemconvHttpMetricsOptions {
+    /** Skip instrumentation for matching request paths (e.g. a metrics scrape route). */
+    exclude?: (path: string) => boolean;
+}
+/**
+ * A `Hooks` bundle recording `http.server.request.duration` per the OTel HTTP
+ * semantic conventions into an {@link OtlpMetricsExporter}:
+ *
+ * - unit `s`, spec bucket boundaries
+ *   ({@link HTTP_SERVER_REQUEST_DURATION_BUCKETS});
+ * - attributes `http.request.method` (well-known set, else `_OTHER`),
+ *   `http.response.status_code`, `url.scheme`, `http.route` (the matched
+ *   route **template** via `ctx.routePath`), and `error.type` (the status
+ *   code, on `5xx` only).
+ *
+ * Only requests that produce a request context are recorded. On the
+ * unmatched-404 fast path the framework skips context construction entirely
+ * (a deliberate allocation optimization), so unmatched floods record nothing
+ * — which is also the strongest possible cardinality guarantee: a hostile
+ * client can never mint metric series from raw paths.
+ *
+ * Install it **before** registering routes (group-hook ordering), or let
+ * `new App({ telemetry: true })` install it for you.
+ *
+ * @param sink - Metrics exporter the duration histogram is recorded into.
+ * @param opts - Optional path exclusion.
+ * @returns A `Hooks` object for `app.use(...)` or `new App({ hooks })`.
+ * @since 1.2.0
+ */
+export declare function semconvHttpMetrics(sink: OtlpMetricsExporter, opts?: SemconvHttpMetricsOptions): Hooks;
+/**
+ * Configuration for the `App` `telemetry` option. Passing `true` is
+ * equivalent to `{}` — everything defaults on, reading the standard `OTEL_*`
+ * environment variables. When no `OTEL_EXPORTER_OTLP_ENDPOINT` is present
+ * (and no explicit `exporter.endpoint` is given) the option is a silent
+ * no-op, so it is safe to leave enabled in development.
+ *
+ * @since 1.2.0
+ */
+export interface TelemetryOptions {
+    /**
+     * Tee the app logger's output to the collector as OTLP logs. Default
+     * `true`. Applies only when the app constructs its own logger (`logger`
+     * omitted, `{ level }`, or defaulted) — a caller-supplied `Logger`
+     * instance controls its own sink and is not intercepted.
+     */
+    logs?: boolean;
+    /**
+     * Record `http.server.request.duration` per the OTel HTTP semantic
+     * conventions and push it to the collector. Default `true`.
+     */
+    metrics?: boolean;
+    /** Endpoint/header/resource/interval overrides shared by both signals. */
+    exporter?: OtlpExporterOptions;
+}
+/**
+ * Internal wiring bundle produced by {@link createAppTelemetry} and consumed
+ * by the `App` constructor. Exposed for advanced composition and tests.
+ *
+ * @since 1.2.0
+ */
+export interface AppTelemetry {
+    /** Log exporter, or `null` when logs are disabled or unconfigured. */
+    logs: OtlpLogExporter | null;
+    /** Metrics exporter, or `null` when metrics are disabled or unconfigured. */
+    metrics: OtlpMetricsExporter | null;
+    /** Hooks to install when HTTP metrics are active. */
+    hooks: Hooks | undefined;
+    /** Logger `write` sink that tees to stdout and the log exporter. */
+    logWrite: ((line: string) => void) | undefined;
+    /** Resolved collector endpoint (no signal path), or `null` when inactive. */
+    endpoint: string | null;
+    /** Flush both signals. Never rejects. */
+    flush(): Promise<void>;
+}
+/**
+ * Build the exporters, hooks, and logger sink for the `App` `telemetry`
+ * option. Returns an inert bundle (all `null`/`undefined`) when no endpoint
+ * is configured, so `telemetry: true` costs nothing in development.
+ *
+ * @param options - The resolved {@link TelemetryOptions}.
+ * @returns The wiring bundle.
+ * @since 1.2.0
+ */
+export declare function createAppTelemetry(options: TelemetryOptions): AppTelemetry;

package/dist/otlp.js

@@ -0,0 +1,527 @@
+/**
+ * OpenTelemetry OTLP push export — logs, metrics, and semantic-convention
+ * HTTP server instrumentation, with zero runtime dependencies.
+ *
+ * Many container platforms run an in-cluster OTel collector and expect
+ * workloads to **push** telemetry: they inject the standard
+ * `OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_EXPORTER_OTLP_HEADERS` /
+ * `OTEL_RESOURCE_ATTRIBUTES` / `OTEL_SERVICE_NAME` variables into every
+ * container and scrape nothing — not stdout, not a `/metrics` route. The
+ * OTel Node SDK covers that with monkey-patching auto-instrumentation, but
+ * its ESM loader hooks are fragile on modern Node and unavailable on edge
+ * runtimes. This module is the framework-native alternative:
+ *
+ * - {@link createOtlpLogExporter} — batched OTLP/HTTP JSON log export;
+ *   tee your logger's `write` sink into it.
+ * - {@link createOtlpMetricsExporter} — cumulative counters + histograms
+ *   pushed as OTLP/HTTP JSON.
+ * - {@link semconvHttpMetrics} — a `Hooks` bundle emitting
+ *   `http.server.request.duration` exactly per the OTel HTTP semantic
+ *   conventions (names, attributes, bucket boundaries), so standard Grafana
+ *   dashboards work unchanged.
+ * - `new App({ telemetry: true })` wires all of the above automatically
+ *   (see {@link TelemetryOptions}).
+ *
+ * Everything is transport-portable (`fetch` + web-standard primitives) and
+ * **fail-safe by contract**: a dead or misconfigured collector never affects
+ * request serving — bounded queues, dropped-batch counters, no retry storms,
+ * and cumulative metric temporality so totals survive failed pushes.
+ *
+ * @module
+ * @since 1.2.0
+ */
+/** Log-queue and batching caps (drop-oldest beyond the queue cap). */
+const LOG_MAX_BATCH = 100;
+const LOG_MAX_QUEUE = 1_000;
+const LOG_FLUSH_INTERVAL_MS = 5_000;
+/** Longest log body / attribute value shipped before truncation. */
+const LOG_MAX_FIELD_LENGTH = 8_192;
+const METRICS_FLUSH_INTERVAL_MS = 15_000;
+/**
+ * Cardinality guard: total metric series (counter + histogram) before new
+ * series are dropped and counted. A hostile client must not be able to mint
+ * unbounded series through attribute values.
+ */
+const METRICS_MAX_SERIES = 2_000;
+/** Longest metric attribute value before truncation (cardinality + memory guard). */
+const METRICS_MAX_ATTR_LENGTH = 256;
+/**
+ * Spec-defined default bucket boundaries for `http.server.request.duration`,
+ * in seconds (OTel HTTP semantic conventions).
+ *
+ * @since 1.2.0
+ */
+export const HTTP_SERVER_REQUEST_DURATION_BUCKETS = [
+    0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10,
+];
+/** OTLP severity numbers keyed by the framework logger's level names. */
+const SEVERITY = {
+    trace: [1, "TRACE"],
+    debug: [5, "DEBUG"],
+    info: [9, "INFO"],
+    warn: [13, "WARN"],
+    error: [17, "ERROR"],
+    fatal: [21, "FATAL"],
+};
+/** Known HTTP methods per the semconv `http.request.method` well-known set. */
+const KNOWN_METHODS = new Set([
+    "GET",
+    "HEAD",
+    "POST",
+    "PUT",
+    "DELETE",
+    "CONNECT",
+    "OPTIONS",
+    "TRACE",
+    "PATCH",
+]);
+/** Portable environment lookup (Node/Bun/Deno-with-node-compat; undefined elsewhere). */
+function envVar(name) {
+    const env = globalThis.process
+        ?.env;
+    return env?.[name];
+}
+/** Parse `key=value,key2=value2` lists (OTEL_EXPORTER_OTLP_HEADERS / OTEL_RESOURCE_ATTRIBUTES). */
+function parseKvList(raw) {
+    const out = {};
+    if (!raw)
+        return out;
+    for (const pair of raw.split(",")) {
+        const trimmed = pair.trim();
+        const idx = trimmed.indexOf("=");
+        if (idx <= 0)
+            continue;
+        out[trimmed.slice(0, idx)] = trimmed.slice(idx + 1);
+    }
+    return out;
+}
+function truncate(value, max) {
+    return value.length <= max ? value : value.slice(0, max);
+}
+function toAttrList(record, maxLength) {
+    return Object.entries(record).map(([key, value]) => ({
+        key,
+        value: { stringValue: truncate(value, maxLength) },
+    }));
+}
+function resolveTransport(signalPath, opts) {
+    const rawEndpoint = opts.endpoint ?? envVar("OTEL_EXPORTER_OTLP_ENDPOINT");
+    if (!rawEndpoint)
+        return null;
+    const base = rawEndpoint.replace(/\/+$/, "").replace(/:4317$/, ":4318");
+    const headers = { "content-type": "application/json" };
+    Object.assign(headers, parseKvList(envVar("OTEL_EXPORTER_OTLP_HEADERS")), opts.headers ?? {});
+    const resource = parseKvList(envVar("OTEL_RESOURCE_ATTRIBUTES"));
+    const serviceName = envVar("OTEL_SERVICE_NAME");
+    if (serviceName && resource["service.name"] === undefined) {
+        resource["service.name"] = serviceName;
+    }
+    Object.assign(resource, opts.resourceAttributes ?? {});
+    return {
+        url: base + signalPath,
+        headers,
+        resourceAttributes: toAttrList(resource, LOG_MAX_FIELD_LENGTH),
+        fetchImpl: opts.fetch ?? fetch,
+    };
+}
+/** Start an `unref`'d repeating flush where the runtime supports timers. */
+function startFlushTimer(intervalMs, flush) {
+    if (intervalMs <= 0 || typeof setInterval !== "function")
+        return;
+    const timer = setInterval(() => void flush(), intervalMs);
+    timer.unref?.();
+}
+function toLogRecord(line) {
+    let level = "info";
+    let body = line;
+    const attributes = [];
+    try {
+        const parsed = JSON.parse(line);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error();
+        if (typeof parsed.level === "string")
+            level = parsed.level;
+        const msg = parsed.msg ?? parsed.message ?? parsed.event;
+        body = typeof msg === "string" ? msg : line;
+        for (const [key, value] of Object.entries(parsed)) {
+            if (key === "level" || key === "msg" || key === "message")
+                continue;
+            attributes.push({
+                key,
+                value: {
+                    stringValue: truncate(typeof value === "string" ? value : JSON.stringify(value) ?? "null", LOG_MAX_FIELD_LENGTH),
+                },
+            });
+        }
+    }
+    catch {
+        // Not a JSON object (boot banner etc.) — ship verbatim as the body.
+    }
+    const [severityNumber, severityText] = SEVERITY[level] ?? SEVERITY.info;
+    return {
+        timeUnixNano: (BigInt(Date.now()) * 1000000n).toString(),
+        severityNumber,
+        severityText,
+        body: { stringValue: truncate(body, LOG_MAX_FIELD_LENGTH) },
+        attributes,
+    };
+}
+/**
+ * Create a batched OTLP/HTTP JSON log exporter, or `null` when no endpoint is
+ * configured (local development, tests) so callers can no-op cheaply.
+ *
+ * Fail-safe by contract: {@link OtlpLogExporter.flush} never rejects, a dead
+ * collector cannot grow the queue past its cap (oldest records are dropped
+ * and counted), and export work is decoupled from request handling.
+ *
+ * @param opts - Endpoint/header/resource overrides; defaults from `OTEL_*` env vars.
+ * @returns The exporter, or `null` when no endpoint is configured.
+ * @since 1.2.0
+ */
+export function createOtlpLogExporter(opts = {}) {
+    const transport = resolveTransport("/v1/logs", opts);
+    if (transport === null)
+        return null;
+    const { url, headers, resourceAttributes, fetchImpl } = transport;
+    const queue = [];
+    let dropped = 0;
+    let flushing = false;
+    async function flush() {
+        if (flushing || queue.length === 0)
+            return;
+        flushing = true;
+        try {
+            while (queue.length > 0) {
+                const batch = queue.splice(0, LOG_MAX_BATCH);
+                const payload = {
+                    resourceLogs: [
+                        {
+                            resource: { attributes: resourceAttributes },
+                            scopeLogs: [{ scope: { name: "daloyjs" }, logRecords: batch }],
+                        },
+                    ],
+                };
+                const res = await fetchImpl(url, {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify(payload),
+                });
+                if (!res.ok)
+                    dropped += 1;
+            }
+        }
+        catch {
+            dropped += 1;
+            queue.length = 0; // never let a dead collector grow the queue
+        }
+        finally {
+            flushing = false;
+        }
+    }
+    startFlushTimer(opts.flushIntervalMs ?? LOG_FLUSH_INTERVAL_MS, flush);
+    return {
+        pushLine(line) {
+            if (queue.length >= LOG_MAX_QUEUE) {
+                queue.shift();
+                dropped += 1;
+            }
+            queue.push(toLogRecord(line.endsWith("\n") ? line.trimEnd() : line));
+        },
+        flush,
+        get droppedBatches() {
+            return dropped;
+        },
+    };
+}
+/**
+ * Create a cumulative OTLP/HTTP JSON metrics exporter, or `null` when no
+ * endpoint is configured.
+ *
+ * Counters export as monotonic cumulative sums and histograms as cumulative
+ * explicit-bounds histograms, so state survives failed pushes (the next
+ * successful push carries the accumulated totals). Total series are capped
+ * ({@link OtlpMetricsExporter.droppedBatches} counts series refused at the
+ * cap) and attribute values are length-truncated — both cardinality guards
+ * against hostile or buggy attribute sources.
+ *
+ * @param opts - Endpoint/header/resource overrides; defaults from `OTEL_*` env vars.
+ * @returns The exporter, or `null` when no endpoint is configured.
+ * @since 1.2.0
+ */
+export function createOtlpMetricsExporter(opts = {}) {
+    const transport = resolveTransport("/v1/metrics", opts);
+    if (transport === null)
+        return null;
+    const { url, headers, resourceAttributes, fetchImpl } = transport;
+    const counters = new Map();
+    const histograms = new Map();
+    let dropped = 0;
+    let flushing = false;
+    let dirty = false;
+    function seriesKey(name, entries) {
+        let key = name;
+        for (const [k, v] of entries)
+            key += "|" + k + "=" + v;
+        return key;
+    }
+    function sortedEntries(attributes) {
+        return Object.entries(attributes)
+            .map(([k, v]) => [k, truncate(v, METRICS_MAX_ATTR_LENGTH)])
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    }
+    function atCapacity() {
+        if (counters.size + histograms.size < METRICS_MAX_SERIES)
+            return false;
+        dropped += 1;
+        return true;
+    }
+    async function flush() {
+        if (flushing || !dirty)
+            return;
+        flushing = true;
+        try {
+            const now = (BigInt(Date.now()) * 1000000n).toString();
+            const sumsByName = new Map();
+            for (const s of counters.values()) {
+                const group = sumsByName.get(s.name);
+                if (group === undefined)
+                    sumsByName.set(s.name, [s]);
+                else
+                    group.push(s);
+            }
+            const histsByName = new Map();
+            for (const h of histograms.values()) {
+                const group = histsByName.get(h.name);
+                if (group === undefined)
+                    histsByName.set(h.name, [h]);
+                else
+                    group.push(h);
+            }
+            const metrics = [];
+            for (const [name, group] of sumsByName) {
+                metrics.push({
+                    name,
+                    unit: "1",
+                    sum: {
+                        aggregationTemporality: 2, // cumulative
+                        isMonotonic: true,
+                        dataPoints: group.map((s) => ({
+                            attributes: s.attributes,
+                            startTimeUnixNano: s.startTimeUnixNano,
+                            timeUnixNano: now,
+                            asDouble: s.total,
+                        })),
+                    },
+                });
+            }
+            for (const [name, group] of histsByName) {
+                metrics.push({
+                    name,
+                    unit: group[0].unit,
+                    histogram: {
+                        aggregationTemporality: 2, // cumulative
+                        dataPoints: group.map((h) => ({
+                            attributes: h.attributes,
+                            startTimeUnixNano: h.startTimeUnixNano,
+                            timeUnixNano: now,
+                            // uint64 fields use the string JSON mapping in OTLP.
+                            count: String(h.count),
+                            sum: h.sum,
+                            bucketCounts: h.bucketCounts.map(String),
+                            explicitBounds: [...h.boundaries],
+                        })),
+                    },
+                });
+            }
+            const payload = {
+                resourceMetrics: [
+                    {
+                        resource: { attributes: resourceAttributes },
+                        scopeMetrics: [{ scope: { name: "daloyjs" }, metrics }],
+                    },
+                ],
+            };
+            const res = await fetchImpl(url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(payload),
+            });
+            if (res.ok)
+                dirty = false;
+            else
+                dropped += 1;
+        }
+        catch {
+            dropped += 1; // totals retained; cumulative temporality self-heals
+        }
+        finally {
+            flushing = false;
+        }
+    }
+    startFlushTimer(opts.flushIntervalMs ?? METRICS_FLUSH_INTERVAL_MS, flush);
+    return {
+        count(name, attributes, value = 1) {
+            if (!Number.isFinite(value) || value < 0)
+                return;
+            const entries = sortedEntries(attributes);
+            const key = seriesKey(name, entries);
+            let s = counters.get(key);
+            if (s === undefined) {
+                if (atCapacity())
+                    return;
+                s = {
+                    name,
+                    attributes: entries.map(([k, v]) => ({ key: k, value: { stringValue: v } })),
+                    total: 0,
+                    startTimeUnixNano: (BigInt(Date.now()) * 1000000n).toString(),
+                };
+                counters.set(key, s);
+            }
+            s.total += value;
+            dirty = true;
+        },
+        record(name, attributes, value, options) {
+            if (!Number.isFinite(value))
+                return;
+            const entries = sortedEntries(attributes);
+            const key = seriesKey(name, entries);
+            let h = histograms.get(key);
+            if (h === undefined) {
+                if (atCapacity())
+                    return;
+                h = {
+                    name,
+                    unit: options.unit,
+                    boundaries: options.boundaries,
+                    attributes: entries.map(([k, v]) => ({ key: k, value: { stringValue: v } })),
+                    count: 0,
+                    sum: 0,
+                    bucketCounts: new Array(options.boundaries.length + 1).fill(0),
+                    startTimeUnixNano: (BigInt(Date.now()) * 1000000n).toString(),
+                };
+                histograms.set(key, h);
+            }
+            h.count += 1;
+            h.sum += value;
+            let bucket = h.boundaries.findIndex((bound) => value <= bound);
+            if (bucket === -1)
+                bucket = h.boundaries.length;
+            h.bucketCounts[bucket] += 1;
+            dirty = true;
+        },
+        flush,
+        get droppedBatches() {
+            return dropped;
+        },
+    };
+}
+/** Monotonic clock in milliseconds, falling back to `Date.now` where needed. */
+function nowMs() {
+    return typeof performance !== "undefined" && typeof performance.now === "function"
+        ? performance.now()
+        : Date.now();
+}
+const SEMCONV_START_TIMES = new WeakMap();
+/**
+ * A `Hooks` bundle recording `http.server.request.duration` per the OTel HTTP
+ * semantic conventions into an {@link OtlpMetricsExporter}:
+ *
+ * - unit `s`, spec bucket boundaries
+ *   ({@link HTTP_SERVER_REQUEST_DURATION_BUCKETS});
+ * - attributes `http.request.method` (well-known set, else `_OTHER`),
+ *   `http.response.status_code`, `url.scheme`, `http.route` (the matched
+ *   route **template** via `ctx.routePath`), and `error.type` (the status
+ *   code, on `5xx` only).
+ *
+ * Only requests that produce a request context are recorded. On the
+ * unmatched-404 fast path the framework skips context construction entirely
+ * (a deliberate allocation optimization), so unmatched floods record nothing
+ * — which is also the strongest possible cardinality guarantee: a hostile
+ * client can never mint metric series from raw paths.
+ *
+ * Install it **before** registering routes (group-hook ordering), or let
+ * `new App({ telemetry: true })` install it for you.
+ *
+ * @param sink - Metrics exporter the duration histogram is recorded into.
+ * @param opts - Optional path exclusion.
+ * @returns A `Hooks` object for `app.use(...)` or `new App({ hooks })`.
+ * @since 1.2.0
+ */
+export function semconvHttpMetrics(sink, opts = {}) {
+    return {
+        onRequest(req) {
+            SEMCONV_START_TIMES.set(req, nowMs());
+        },
+        onResponse(res, ctx) {
+            const request = ctx?.request;
+            if (request === undefined)
+                return;
+            const started = SEMCONV_START_TIMES.get(request);
+            if (started === undefined)
+                return;
+            SEMCONV_START_TIMES.delete(request);
+            let pathname = "/";
+            let scheme = "http";
+            try {
+                const parsed = new URL(request.url);
+                pathname = parsed.pathname;
+                scheme = parsed.protocol.replace(":", "");
+            }
+            catch {
+                /* malformed URL — keep the fallbacks */
+            }
+            if (opts.exclude !== undefined && opts.exclude(pathname))
+                return;
+            const rawMethod = request.method.toUpperCase();
+            const attributes = {
+                "http.request.method": KNOWN_METHODS.has(rawMethod) ? rawMethod : "_OTHER",
+                "http.response.status_code": String(res.status),
+                "url.scheme": scheme,
+            };
+            // Spec: http.route only when a route template is known. Never the raw
+            // pathname — an unmatched-path flood must not mint metric series.
+            const routePath = ctx?.routePath;
+            if (typeof routePath === "string")
+                attributes["http.route"] = routePath;
+            if (res.status >= 500)
+                attributes["error.type"] = String(res.status);
+            sink.record("http.server.request.duration", attributes, (nowMs() - started) / 1000, { unit: "s", boundaries: HTTP_SERVER_REQUEST_DURATION_BUCKETS });
+        },
+    };
+}
+/**
+ * Build the exporters, hooks, and logger sink for the `App` `telemetry`
+ * option. Returns an inert bundle (all `null`/`undefined`) when no endpoint
+ * is configured, so `telemetry: true` costs nothing in development.
+ *
+ * @param options - The resolved {@link TelemetryOptions}.
+ * @returns The wiring bundle.
+ * @since 1.2.0
+ */
+export function createAppTelemetry(options) {
+    const exporterOpts = options.exporter ?? {};
+    const logs = options.logs === false ? null : createOtlpLogExporter(exporterOpts);
+    const metrics = options.metrics === false ? null : createOtlpMetricsExporter(exporterOpts);
+    const logWrite = logs === null
+        ? undefined
+        : (line) => {
+            const proc = globalThis.process;
+            if (proc?.stdout?.write !== undefined)
+                proc.stdout.write(line + "\n");
+            // eslint-disable-next-line no-console
+            else
+                console.log(line);
+            logs.pushLine(line);
+        };
+    const endpointRaw = exporterOpts.endpoint ?? envVar("OTEL_EXPORTER_OTLP_ENDPOINT") ?? null;
+    return {
+        logs,
+        metrics,
+        hooks: metrics === null ? undefined : semconvHttpMetrics(metrics),
+        logWrite,
+        endpoint: endpointRaw,
+        async flush() {
+            await Promise.all([logs?.flush(), metrics?.flush()]);
+        },
+    };
+}

package/dist/sbom.cdx.json

@@ -1,15 +1,15 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:6f1d01b1-95cd-5475-994d-9d54a26deac5",
+  "serialNumber": "urn:uuid:3d6cece6-6c87-5815-9301-8b0be8579da5",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-07T14:15:51.163Z",
+    "timestamp": "2026-08-20T11:51:20.093Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "1.1.0"
+        "version": "1.2.0"
       }
     ],
     "authors": [
@@ -19,11 +19,11 @@
     ],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/@daloyjs/core@1.1.0",
+      "bom-ref": "pkg:npm/@daloyjs/core@1.2.0",
       "name": "@daloyjs/core",
-      "version": "1.1.0",
+      "version": "1.2.0",
       "description": "DaloyJS is a runtime-portable, contract-first TypeScript web framework with built-in OpenAPI (Hey API), typed client generation, large-scale maintainability, and security-first defaults. Hono-grade portability, Elysia-grade DX, FastAPI-grade docs, Fastify-grade ops — distributed via pnpm.",
-      "purl": "pkg:npm/@daloyjs/core@1.1.0",
+      "purl": "pkg:npm/@daloyjs/core@1.2.0",
       "licenses": [
         {
           "license": {
@@ -46,9 +46,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag--daloyjs-core-1.1.0",
+        "tagId": "swidtag--daloyjs-core-1.2.0",
         "name": "@daloyjs/core",
-        "version": "1.1.0",
+        "version": "1.2.0",
         "tagVersion": 0,
         "patch": false
       }
@@ -57,7 +57,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/@daloyjs/core@1.1.0",
+      "ref": "pkg:npm/@daloyjs/core@1.2.0",
       "dependsOn": []
     }
   ]

package/dist/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@daloyjs/core-1.1.0",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.1.0-6f1d01b1-95cd-5475-994d-9d54a26deac5",
+  "name": "@daloyjs/core-1.2.0",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.2.0-3d6cece6-6c87-5815-9301-8b0be8579da5",
   "creationInfo": {
-    "created": "2026-08-07T14:15:51.163Z",
+    "created": "2026-08-20T11:51:20.093Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package--daloyjs-core",
       "name": "@daloyjs/core",
-      "versionInfo": "1.1.0",
+      "versionInfo": "1.2.0",
       "downloadLocation": "https://github.com/daloyjs/daloy",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
@@ -27,7 +27,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/@daloyjs/core@1.1.0"
+          "referenceLocator": "pkg:npm/@daloyjs/core@1.2.0"
         }
       ]
     }

package/dist/types.d.ts

@@ -268,6 +268,15 @@ export interface BaseContext<P extends string, R extends RequestSchemas | undefi
     body: InferRequest<R, P>["body"];
     /** Mutable per-request state. Plugin-augmented context lives here. */
     state: AppState & Record<string, unknown>;
+    /**
+     * The matched route's path **template** (e.g. `/books/:id`), set as soon as
+     * routing succeeds. `undefined` on framework-synthesised contexts (404/405
+     * error contexts, OPTIONS preflight). Use it for low-cardinality metric
+     * labels (`http.route`) instead of the raw request path.
+     *
+     * @since 1.2.0
+     */
+    routePath?: string;
     /** Convenience response helpers (do not bypass schema validation). */
     set: {
         status?: number;
@@ -299,6 +308,13 @@ export interface PreBodyContext<P extends string = string> {
     body: undefined;
     /** Mutable per-request state shared with later hooks and the handler. */
     state: AppState & Record<string, unknown>;
+    /**
+     * The matched route's path template (routing has already succeeded when
+     * `preBody` runs). See {@link BaseContext.routePath}.
+     *
+     * @since 1.2.0
+     */
+    routePath?: string;
     /** Response headers/status available to a short-circuiting perimeter hook. */
     set: {
         status?: number;
@@ -376,8 +392,8 @@ export interface Hooks {
      * the existing response. Multiple `onSend` hooks compose pipeline-style.
      */
     onSend?: (res: Response, ctx: BaseContext<any, any> | undefined) => void | Response | Promise<void | Response>;
-    /** Fire-and-forget observer of the final outgoing `Response` (logging, metrics). Runs last; cannot alter the response. */
-    onResponse?: (res: Response) => void | Promise<void>;
+    /** Fire-and-forget observer of the final outgoing `Response` (logging, metrics). Runs last; cannot alter the response. `ctx` is `undefined` when the error occurred before context was built. */
+    onResponse?: (res: Response, ctx?: BaseContext<any, any> | undefined) => void | Promise<void>;
 }
 /**
  * Declarative description of one HTTP endpoint. The single source of truth

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daloyjs/core",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "DaloyJS is a runtime-portable, contract-first TypeScript web framework with built-in OpenAPI (Hey API), typed client generation, large-scale maintainability, and security-first defaults. Hono-grade portability, Elysia-grade DX, FastAPI-grade docs, Fastify-grade ops \u2014 distributed via pnpm.",
   "type": "module",
   "publishConfig": {
@@ -154,6 +154,10 @@
       "types": "./dist/metrics.d.ts",
       "import": "./dist/metrics.js"
     },
+    "./otlp": {
+      "types": "./dist/otlp.d.ts",
+      "import": "./dist/otlp.js"
+    },
     "./fetch-resilience": {
       "types": "./dist/fetch-resilience.d.ts",
       "import": "./dist/fetch-resilience.js"