@daloyjs/core 1.1.1 → 1.2.1

package/dist/combine.js

@@ -5,7 +5,7 @@
  *
  * @since 0.19.0
  */
-import { _mergePreBodyWithEarlyRejections, EARLY_REJECTION_HOOK_MARKER } from "./middleware.js";
+import { _mergePreBodyWithEarlyRejections, EARLY_REJECTION_HOOK_MARKER, } from "./middleware.js";
 /**
  * Run every supplied {@link Hooks} bundle in order, pipeline-style.
  * Equivalent to passing the bundles to `app.use(...)` one after another,
@@ -88,7 +88,9 @@ export function some(...layers) {
                 return [
                     async (ctx) => {
                         const early = await hooks.preBody(ctx);
-                        return early instanceof Response ? early : hooks.beforeHandle(ctx);
+                        return early instanceof Response
+                            ? early
+                            : hooks.beforeHandle(ctx);
                     },
                 ];
             }
@@ -152,7 +154,9 @@ export function some(...layers) {
  */
 export function except(when, hooks) {
     const earlyRejectionHooks = hooks[EARLY_REJECTION_HOOK_MARKER];
-    if (!hooks.preBody && !hooks.beforeHandle && !Array.isArray(earlyRejectionHooks))
+    if (!hooks.preBody &&
+        !hooks.beforeHandle &&
+        !Array.isArray(earlyRejectionHooks))
         return hooks;
     const matches = compileExceptMatcher(when);
     const wrapped = { ...hooks };
@@ -166,11 +170,11 @@ export function except(when, hooks) {
     }
     if (hooks.preBody) {
         const original = hooks.preBody;
-        wrapped.preBody = async (ctx) => ((await matches(ctx)) ? undefined : original(ctx));
+        wrapped.preBody = async (ctx) => (await matches(ctx)) ? undefined : original(ctx);
     }
     if (hooks.beforeHandle) {
         const original = hooks.beforeHandle;
-        wrapped.beforeHandle = async (ctx) => ((await matches(ctx)) ? undefined : original(ctx));
+        wrapped.beforeHandle = async (ctx) => (await matches(ctx)) ? undefined : original(ctx);
     }
     return wrapped;
 }
@@ -206,7 +210,9 @@ function compilePathPattern(pattern) {
     return (path) => regex.test(path);
 }
 function mergeCombineHooks(layers) {
-    const pick = (key) => layers.map((h) => h[key]).filter((f) => typeof f === "function");
+    const pick = (key) => layers
+        .map((h) => h[key])
+        .filter((f) => typeof f === "function");
     const merged = {};
     const onRequest = pick("onRequest");
     if (onRequest.length > 0) {
@@ -266,9 +272,9 @@ function mergeCombineHooks(layers) {
     }
     const onResponse = pick("onResponse");
     if (onResponse.length > 0) {
-        merged.onResponse = async (res) => {
+        merged.onResponse = async (res, ctx) => {
             for (const fn of onResponse)
-                await fn(res);
+                await fn(res, ctx);
         };
     }
     // Forward symbol-keyed security markers (CORS / CSRF / session /

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.d.ts

@@ -17,8 +17,11 @@
  *   `http_requests_in_flight`) into a registry.
  *
  * Everything is built on Web-standard primitives (plus optional `process.*`
- * gauges guarded for non-Node runtimes), so it runs unchanged on Node, Bun,
- * Deno, Cloudflare Workers, and Vercel.
+ * gauges guarded for non-Node runtimes). The registry and renderer run on
+ * Node, Bun, Deno, Cloudflare Workers, and Vercel; **pull scraping
+ * (`GET /metrics`) is only a service-wide signal on a long-lived process**.
+ * On ephemeral isolates use `new App({ telemetry: true })` (OTLP push)
+ * instead of scraping `/metrics`.
  *
  * @module
  * @since 0.37.0
@@ -94,7 +97,14 @@ export declare class Histogram extends Metric {
 }
 /** Options for {@link MetricsRegistry}. */
 export interface MetricsRegistryOptions {
-    /** Prefix applied to every metric name. Default `"daloy_"`. Pass `""` for none. */
+    /**
+     * Prefix applied to every metric name except the framework drop counter.
+     * Default `""` so process gauges (`process_resident_memory_bytes`) and HTTP
+     * RED series (`http_requests_total`) match the names stock Grafana panels
+     * already query. Pass `"daloy_"` (or any other prefix) to namespace them.
+     * The cardinality-drop meta-metric stays `daloy_metrics_series_dropped_total`
+     * when this is empty, because it is a DaloyJS-specific series.
+     */
     prefix?: string;
     /**
      * Hard cap on the number of distinct series **per metric**. Once reached,
@@ -172,15 +182,19 @@ export interface HttpMetricsOptions {
     registry: MetricsRegistry;
     /**
      * Resolve the low-cardinality `route` label from the request context.
-     * Strongly recommended: return the route **template** (e.g. `/books/:id`),
-     * not the raw path, to keep series cardinality bounded. When omitted the
-     * request pathname is used, capped by {@link HttpMetricsOptions.maxRouteCardinality}.
+     * When omitted, the matched route **template** (`ctx.routePath`, e.g.
+     * `/books/:id`) is used. That is bounded by the route table, so a hostile
+     * client cannot mint series from raw paths. A custom resolver that returns
+     * a raw pathname should still keep cardinality bounded; the pathname
+     * fallback (no template on the context) is capped by
+     * {@link HttpMetricsOptions.maxRouteCardinality}.
      */
     route?: (ctx: BaseContext<any, any>) => string | undefined;
     /**
-     * Maximum distinct values for the default (pathname-derived) `route` label
-     * before further values collapse to `"<other>"`. Ignored when a custom
-     * {@link HttpMetricsOptions.route} resolver is supplied. Default `100`.
+     * Maximum distinct values for the pathname fallback `route` label (used
+     * only when {@link HttpMetricsOptions.route} is omitted **and**
+     * `ctx.routePath` is missing) before further values collapse to
+     * `"<other>"`. Ignored when a custom resolver is supplied. Default `100`.
      */
     maxRouteCardinality?: number;
     /** Skip instrumentation for matching request paths (e.g. the scrape route). */

package/dist/metrics.js

@@ -17,8 +17,11 @@
  *   `http_requests_in_flight`) into a registry.
  *
  * Everything is built on Web-standard primitives (plus optional `process.*`
- * gauges guarded for non-Node runtimes), so it runs unchanged on Node, Bun,
- * Deno, Cloudflare Workers, and Vercel.
+ * gauges guarded for non-Node runtimes). The registry and renderer run on
+ * Node, Bun, Deno, Cloudflare Workers, and Vercel; **pull scraping
+ * (`GET /metrics`) is only a service-wide signal on a long-lived process**.
+ * On ephemeral isolates use `new App({ telemetry: true })` (OTLP push)
+ * instead of scraping `/metrics`.
  *
  * @module
  * @since 0.37.0
@@ -49,7 +52,10 @@ function escapeHelp(value) {
  * out of the `{...}` block and injecting forged samples.
  */
 function escapeLabelValue(value) {
-    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+    return value
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, "\\n");
 }
 /**
  * Validate and normalize a label bag: every key must match the Prometheus
@@ -137,7 +143,10 @@ export class Counter extends Metric {
     }
     /** @internal */
     render() {
-        const lines = [`# HELP ${this.name} ${escapeHelp(this.help)}`, `# TYPE ${this.name} counter`];
+        const lines = [
+            `# HELP ${this.name} ${escapeHelp(this.help)}`,
+            `# TYPE ${this.name} counter`,
+        ];
         for (const { labels, value } of this.series.values()) {
             lines.push(`${this.name}${renderLabelBlock(labels)} ${value}`);
         }
@@ -183,7 +192,10 @@ export class Gauge extends Metric {
     }
     /** @internal */
     render() {
-        const lines = [`# HELP ${this.name} ${escapeHelp(this.help)}`, `# TYPE ${this.name} gauge`];
+        const lines = [
+            `# HELP ${this.name} ${escapeHelp(this.help)}`,
+            `# TYPE ${this.name} gauge`,
+        ];
         for (const { labels, value } of this.series.values()) {
             lines.push(`${this.name}${renderLabelBlock(labels)} ${value}`);
         }
@@ -219,7 +231,12 @@ export class Histogram extends Metric {
         if (!s) {
             if (!this.registry._admitSeries(this.series.size))
                 return;
-            s = { labels: entries, counts: new Array(this.bounds.length).fill(0), sum: 0, count: 0 };
+            s = {
+                labels: entries,
+                counts: new Array(this.bounds.length).fill(0),
+                sum: 0,
+                count: 0,
+            };
             this.series.set(key, s);
         }
         s.count += 1;
@@ -231,7 +248,10 @@ export class Histogram extends Metric {
     }
     /** @internal */
     render() {
-        const lines = [`# HELP ${this.name} ${escapeHelp(this.help)}`, `# TYPE ${this.name} histogram`];
+        const lines = [
+            `# HELP ${this.name} ${escapeHelp(this.help)}`,
+            `# TYPE ${this.name} histogram`,
+        ];
         for (const s of this.series.values()) {
             for (let i = 0; i < this.bounds.length; i++) {
                 lines.push(`${this.name}_bucket${renderLabelBlock(s.labels, ["le", String(this.bounds[i])])} ${s.counts[i]}`);
@@ -272,7 +292,7 @@ export class MetricsRegistry {
     collectors = [];
     droppedCounter;
     constructor(opts = {}) {
-        this.prefix = opts.prefix ?? "daloy_";
+        this.prefix = opts.prefix ?? "";
         this.maxSeries = opts.maxSeries ?? 5000;
         if (!Number.isInteger(this.maxSeries) || this.maxSeries <= 0) {
             throw new Error("MetricsRegistry maxSeries must be a positive integer.");
@@ -345,7 +365,9 @@ export class MetricsRegistry {
         return metric;
     }
     registerDefaultMetrics() {
-        this.droppedCounter = this.counter("metrics_series_dropped_total", "Series dropped after hitting the per-metric cardinality cap.");
+        this.droppedCounter = this.counter(this.prefix === ""
+            ? "daloy_metrics_series_dropped_total"
+            : "metrics_series_dropped_total", "Series dropped after hitting the per-metric cardinality cap.");
         if (typeof process === "undefined")
             return;
         const rss = this.gauge("process_resident_memory_bytes", "Resident memory size in bytes.");
@@ -369,7 +391,8 @@ export class MetricsRegistry {
 }
 /** Monotonic clock in milliseconds, falling back to `Date.now` where needed. */
 function nowMs() {
-    return typeof performance !== "undefined" && typeof performance.now === "function"
+    return typeof performance !== "undefined" &&
+        typeof performance.now === "function"
         ? performance.now()
         : Date.now();
 }
@@ -401,6 +424,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,268 @@
+/**
+ * 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,
+ * a timeout on every export POST, and cumulative metric temporality so
+ * totals survive failed pushes. Long-lived runtimes flush on an `unref`'d
+ * interval plus graceful shutdown; isolate runtimes (Workers, Vercel, Lambda)
+ * flush per request via the adapters' `waitUntil` / handler-await path.
+ *
+ * @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 / via the serverless
+     * adapters' per-request flush.
+     */
+    flushIntervalMs?: number;
+    /**
+     * Abort an in-flight export POST after this many ms so a blackholed
+     * collector cannot latch `flushing` forever. Default `5000`. Set `0` to
+     * wait indefinitely (tests that drive `fetch` themselves).
+     */
+    flushTimeoutMs?: 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>;
+    /**
+     * Mixed drop counter: overflowed log *lines* (one per `shift()` at the
+     * queue cap) plus failed export *POSTs* (collector 4xx/5xx, network error,
+     * timeout, or disallowed redirect). Not a count of failed HTTP batches
+     * alone — compare against queue depth under load, not "POSTs that failed".
+     */
+    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>;
+    /**
+     * Mixed drop counter: failed export *POSTs* (collector 4xx/5xx, network
+     * error, timeout, or disallowed redirect) plus *series* refused at the
+     * cardinality cap. A cardinality attack inflates this without any POST
+     * failing.
+     */
+    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. A caller-supplied
+ * `Logger` instance is not intercepted (it owns its own sink). On isolate
+ * runtimes use `toFetchHandler` / `toLambdaHandler` so a per-request flush
+ * actually runs; Node/Bun/Deno long-lived processes flush on the interval
+ * and on shutdown. The collector endpoint is operator config, so export
+ * uses raw `fetch` (not `fetchGuard`) — the same trust class as a database
+ * URL.
+ *
+ * @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;