@lunora/do 1.0.0-alpha.39 → 1.0.0-alpha.40

package/dist/index.d.mts

@@ -4758,6 +4758,24 @@ declare abstract class ShardDO {
    * fields.
    */
   private currentRequestTrace;
+  /**
+   * Per-trace head-sampling state, keyed by `traceId` so concurrent dispatches on
+   * the same DO instance can't clobber each other's decision. A DO interleaves
+   * dispatches across `await` points, and the span-recording and error-flush
+   * choke points run after a span body (or the whole dispatch) settles — by which
+   * point a flat per-instance field could have been overwritten by a sibling
+   * dispatch (the same hazard `dispatchTrace` guards against for the trace anchor).
+   * Each entry holds `sampled` (the inbound `traceparent` flag; absent means keep,
+   * so alarms, subscription re-runs and non-Lunora callers export exactly as
+   * before — when false, `ctx.trace` INTERNAL spans are held out of the live export
+   * and re-decided in the dispatch `finally` as a tail bias), `keepErrors` (the
+   * runtime's `x-lunora-sample-errors` / `alwaysSampleErrors` toggle — a sampled-out
+   * trace that errored is still exported whole unless off), and `sink` (captured
+   * when a sampled-out span is first held, so the `finally` can flush the trace's
+   * held spans). Registered at dispatch entry by the dispatch's own `traceId`, read
+   * by `span.traceId`, and deleted in the `finally`.
+   */
+  private traceSampling;
   /**
    * Client-issued idempotency key for the in-flight mutation, forwarded via the
    * `x-lunora-mutation-id` header. When set, the dispatch path dedups the call
@@ -5941,8 +5959,35 @@ declare abstract class ShardDO {
    * `sink.onSpan`. Best-effort throughout, exactly like {@link recordUserLog}:
    * a span is recorded *after* its body already settled, so letting a telemetry
    * failure escape here would turn a succeeded operation into a failed request.
+   *
+   * The span is ALWAYS buffered locally (the Studio Traces panel is a full
+   * "recent traces on this instance" readout, unaffected by sampling). Only the
+   * export to the sink is sampled: when the active dispatch's trace was sampled
+   * OUT (its inbound `traceparent` flag was `00`), the span is held back rather
+   * than streamed — the dispatch `finally` re-decides once the trace's error
+   * status is known ({@link flushSampledOutTrace}), so an errored trace is still
+   * exported whole (tail bias). Spans from a sampled-in dispatch, or from another
+   * trace (a subscription re-run mints its own anchor), stream immediately.
    */
   protected recordSpan(span: SpanEvent, sink?: TelemetrySink): void;
+  /**
+   * Hand one span to `sink.onSpan`, swallowing sink throws. The DO's `waitUntil`
+   * is threaded so a network sink (otlpSink) can keep its export alive past the
+   * response, matching the log path. Extracted so both the live-stream path in
+   * {@link recordSpan} and the deferred error-keep flush in
+   * {@link flushSampledOutTrace} share one guarded emit.
+   */
+  private emitSpan;
+  /**
+   * Export-boundary decision for a sampled-out trace, run from the dispatch
+   * `finally` once the error status is known. A sampled-in trace already
+   * streamed live, so this returns early for it; a sampled-out trace exports its
+   * held `ctx.trace` spans only when `alwaysSampleErrors` is set AND the trace
+   * errored (the dispatch threw, or a held span settled `ok: false`) — the tail
+   * bias — and otherwise drops them. Held spans are read back from the local ring
+   * (excluding the synthetic dispatch root, which never goes to `onSpan`).
+   */
+  private flushSampledOutTrace;
   /**
    * Assemble the per-socket {@link LifecycleDispatchInfo} from its attachment:
    * the verified identity to replay and the {@link LifecycleEvent} the hooks

package/dist/index.d.ts

@@ -4758,6 +4758,24 @@ declare abstract class ShardDO {
    * fields.
    */
   private currentRequestTrace;
+  /**
+   * Per-trace head-sampling state, keyed by `traceId` so concurrent dispatches on
+   * the same DO instance can't clobber each other's decision. A DO interleaves
+   * dispatches across `await` points, and the span-recording and error-flush
+   * choke points run after a span body (or the whole dispatch) settles — by which
+   * point a flat per-instance field could have been overwritten by a sibling
+   * dispatch (the same hazard `dispatchTrace` guards against for the trace anchor).
+   * Each entry holds `sampled` (the inbound `traceparent` flag; absent means keep,
+   * so alarms, subscription re-runs and non-Lunora callers export exactly as
+   * before — when false, `ctx.trace` INTERNAL spans are held out of the live export
+   * and re-decided in the dispatch `finally` as a tail bias), `keepErrors` (the
+   * runtime's `x-lunora-sample-errors` / `alwaysSampleErrors` toggle — a sampled-out
+   * trace that errored is still exported whole unless off), and `sink` (captured
+   * when a sampled-out span is first held, so the `finally` can flush the trace's
+   * held spans). Registered at dispatch entry by the dispatch's own `traceId`, read
+   * by `span.traceId`, and deleted in the `finally`.
+   */
+  private traceSampling;
   /**
    * Client-issued idempotency key for the in-flight mutation, forwarded via the
    * `x-lunora-mutation-id` header. When set, the dispatch path dedups the call
@@ -5941,8 +5959,35 @@ declare abstract class ShardDO {
    * `sink.onSpan`. Best-effort throughout, exactly like {@link recordUserLog}:
    * a span is recorded *after* its body already settled, so letting a telemetry
    * failure escape here would turn a succeeded operation into a failed request.
+   *
+   * The span is ALWAYS buffered locally (the Studio Traces panel is a full
+   * "recent traces on this instance" readout, unaffected by sampling). Only the
+   * export to the sink is sampled: when the active dispatch's trace was sampled
+   * OUT (its inbound `traceparent` flag was `00`), the span is held back rather
+   * than streamed — the dispatch `finally` re-decides once the trace's error
+   * status is known ({@link flushSampledOutTrace}), so an errored trace is still
+   * exported whole (tail bias). Spans from a sampled-in dispatch, or from another
+   * trace (a subscription re-run mints its own anchor), stream immediately.
    */
   protected recordSpan(span: SpanEvent, sink?: TelemetrySink): void;
+  /**
+   * Hand one span to `sink.onSpan`, swallowing sink throws. The DO's `waitUntil`
+   * is threaded so a network sink (otlpSink) can keep its export alive past the
+   * response, matching the log path. Extracted so both the live-stream path in
+   * {@link recordSpan} and the deferred error-keep flush in
+   * {@link flushSampledOutTrace} share one guarded emit.
+   */
+  private emitSpan;
+  /**
+   * Export-boundary decision for a sampled-out trace, run from the dispatch
+   * `finally` once the error status is known. A sampled-in trace already
+   * streamed live, so this returns early for it; a sampled-out trace exports its
+   * held `ctx.trace` spans only when `alwaysSampleErrors` is set AND the trace
+   * errored (the dispatch threw, or a held span settled `ok: false`) — the tail
+   * bias — and otherwise drops them. Held spans are read back from the local ring
+   * (excluding the synthetic dispatch root, which never goes to `onSpan`).
+   */
+  private flushSampledOutTrace;
   /**
    * Assemble the per-socket {@link LifecycleDispatchInfo} from its attachment:
    * the verified identity to replay and the {@link LifecycleEvent} the hooks

package/dist/index.mjs

@@ -3,7 +3,7 @@ export { AGGREGATE_SQL_FUNCTION, aggregateSqlFunction, matchesStaticWhere, norma
 export { aggregateTableName, coerceAggregateNumber, encodeAggregateKey, foldAggregateTally, readAggregateValue } from './packem_shared/aggregateTableName-CxNqY1Sl.mjs';
 export { CountRlsUnsupportedError, mergeWhere, planAggregateLookup, selectIndexForAggregate, selectIndexForCount, selectIndexForGroupBy } from './packem_shared/CountRlsUnsupportedError-BGxj0pgS.mjs';
 export { AUTH_METRICS_BUCKETS_TABLE, AUTH_METRICS_BUCKET_MS, AUTH_METRICS_BUCKET_RETENTION, AUTH_METRICS_TABLE, ensureAuthMetricsTables, readAuthMetrics, recordAuthEvent } from './packem_shared/AUTH_METRICS_BUCKETS_TABLE-CiHHYeJi.mjs';
-export { c as createMetrics, a as createTracer, d as dispatchRootSpan } from './packem_shared/context-telemetry-CqcOObBl.mjs';
+export { c as createMetrics, a as createTracer, d as dispatchRootSpan } from './packem_shared/context-telemetry-BVSDl6PU.mjs';
 export { NotUniqueError, assertValidClientId, createShardCtxDb, normalizeIdStructurally } from './packem_shared/NotUniqueError-DbtlWwcG.mjs';
 export { DATA_MIGRATION_STATE_TABLE, readMigrationStatus, runDataMigration } from './packem_shared/DATA_MIGRATION_STATE_TABLE-CYwBpyTr.mjs';
 export { SCAN_DEP, createDependencyTracker, depKey } from './packem_shared/SCAN_DEP-DLJF8dsj.mjs';
@@ -28,7 +28,7 @@ export { RLS_UNWRAP_SYMBOL, RlsRequiredError, guardWriter } from './packem_share
 export { buildFtsMatch, ftsTableName, scoreDocument, stringifySearchText, tokenizeSearch } from './packem_shared/buildFtsMatch-BLEMawrp.mjs';
 export { M as MIN_ADMIN_TOKEN_LENGTH, a as MIN_AUTH_SECRET_LENGTH, b as buildSecurityAudit } from './packem_shared/security-audit-CucgBice.mjs';
 export { SESSION_DO_TTL_DEFAULT, SessionDO } from './packem_shared/SESSION_DO_TTL_DEFAULT-BnSKgVO4.mjs';
-export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO } from './packem_shared/ROOT_DO_SIZE_WARN_BYTES-CJGwzfoT.mjs';
+export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO } from './packem_shared/ROOT_DO_SIZE_WARN_BYTES-COEnnBhO.mjs';
 export { SHARD_REGISTRY_DO_NAME, ShardRegistryDO } from './packem_shared/SHARD_REGISTRY_DO_NAME-D99roc-r.mjs';
 export { MAX_SQL_ROWS, assertReadonly, runReadonlySql } from './packem_shared/MAX_SQL_ROWS-iFAA8FbD.mjs';
 export { createSystemReader } from './packem_shared/createSystemReader-D12eNH13.mjs';

package/dist/packem_shared/{ROOT_DO_SIZE_WARN_BYTES-CJGwzfoT.mjs → ROOT_DO_SIZE_WARN_BYTES-COEnnBhO.mjs}

@@ -2,10 +2,10 @@ import { LunoraError, toErrorBody } from '@lunora/errors';
 import { drizzle } from 'drizzle-orm/durable-sqlite';
 import { c as constantTimeEqual } from './constant-time-equal-BVRWZgES.mjs';
 import { j as jsonResponse } from './json-response-BdbtpOhm.mjs';
+import { n as normalizeLogFields, r as resolveTraceAnchor, p as parseTraceparent, a as createTracer, c as createMetrics, d as dispatchRootSpan } from './context-telemetry-BVSDl6PU.mjs';
 import { e as encodeWire, d as decodeWire } from './wire-codec-CzQc1pvf.mjs';
 import { parseExportShardArgs, parseImportShardArgs } from './exportShardRows-Dy3oFZ26.mjs';
 import { recordAuthEvent, readAuthMetrics } from './AUTH_METRICS_BUCKETS_TABLE-CiHHYeJi.mjs';
-import { n as normalizeLogFields, r as resolveTraceAnchor, a as createTracer, c as createMetrics, d as dispatchRootSpan } from './context-telemetry-CqcOObBl.mjs';
 import { DATA_MIGRATION_STATE_TABLE, readMigrationStatus } from './DATA_MIGRATION_STATE_TABLE-CYwBpyTr.mjs';
 import { SCAN_DEP, createDependencyTracker, tableFromDepKey } from './SCAN_DEP-DLJF8dsj.mjs';
 import { readFunctionMetricsTotals, readFunctionMetricIndexHits, recordFunctionMetric, mergeScanAttribution, readFunctionMetrics, readFunctionMetricBuckets } from './FUNCTION_METRICS_BUCKETS_TABLE-UDNVD7FS.mjs';
@@ -2678,6 +2678,24 @@ class ShardDO {
    * fields.
    */
   currentRequestTrace;
+  /**
+   * Per-trace head-sampling state, keyed by `traceId` so concurrent dispatches on
+   * the same DO instance can't clobber each other's decision. A DO interleaves
+   * dispatches across `await` points, and the span-recording and error-flush
+   * choke points run after a span body (or the whole dispatch) settles — by which
+   * point a flat per-instance field could have been overwritten by a sibling
+   * dispatch (the same hazard `dispatchTrace` guards against for the trace anchor).
+   * Each entry holds `sampled` (the inbound `traceparent` flag; absent means keep,
+   * so alarms, subscription re-runs and non-Lunora callers export exactly as
+   * before — when false, `ctx.trace` INTERNAL spans are held out of the live export
+   * and re-decided in the dispatch `finally` as a tail bias), `keepErrors` (the
+   * runtime's `x-lunora-sample-errors` / `alwaysSampleErrors` toggle — a sampled-out
+   * trace that errored is still exported whole unless off), and `sink` (captured
+   * when a sampled-out span is first held, so the `finally` can flush the trace's
+   * held spans). Registered at dispatch entry by the dispatch's own `traceId`, read
+   * by `span.traceId`, and deleted in the `finally`.
+   */
+  traceSampling = /* @__PURE__ */ new Map();
   /**
    * Client-issued idempotency key for the in-flight mutation, forwarded via the
    * `x-lunora-mutation-id` header. When set, the dispatch path dedups the call
@@ -3013,6 +3031,10 @@ class ShardDO {
     this.currentRequestTraceparent = request.headers.get("traceparent") ?? void 0;
     this.currentRequestTrace = resolveTraceAnchor(this.currentRequestTraceparent);
     const dispatchTrace = this.currentRequestTrace;
+    this.traceSampling.set(dispatchTrace.traceId, {
+      keepErrors: request.headers.get("x-lunora-sample-errors") !== "0",
+      sampled: parseTraceparent(this.currentRequestTraceparent)?.sampled ?? true
+    });
     this.currentRequestReadTables = void 0;
     this.currentRequestCacheHit = void 0;
     this.metrics.requests += 1;
@@ -3075,6 +3097,8 @@ class ShardDO {
       if (this.spans.hasTrace(dispatchTrace.traceId)) {
         this.recordDispatchRootSpan(payload.functionPath, dispatchStartedAt, dispatchError, dispatchTrace);
       }
+      this.flushSampledOutTrace(dispatchTrace, dispatchError !== void 0);
+      this.traceSampling.delete(dispatchTrace.traceId);
       this.currentRequestTrace = void 0;
       this.currentRequestBookmark = void 0;
       this.currentResponseBookmark = void 0;
@@ -4852,6 +4876,15 @@ class ShardDO {
    * `sink.onSpan`. Best-effort throughout, exactly like {@link recordUserLog}:
    * a span is recorded *after* its body already settled, so letting a telemetry
    * failure escape here would turn a succeeded operation into a failed request.
+   *
+   * The span is ALWAYS buffered locally (the Studio Traces panel is a full
+   * "recent traces on this instance" readout, unaffected by sampling). Only the
+   * export to the sink is sampled: when the active dispatch's trace was sampled
+   * OUT (its inbound `traceparent` flag was `00`), the span is held back rather
+   * than streamed — the dispatch `finally` re-decides once the trace's error
+   * status is known ({@link flushSampledOutTrace}), so an errored trace is still
+   * exported whole (tail bias). Spans from a sampled-in dispatch, or from another
+   * trace (a subscription re-run mints its own anchor), stream immediately.
    */
   // eslint-disable-next-line @typescript-eslint/member-ordering -- kept in the span-recording cluster (next to recordDispatchRootSpan) for cohesion rather than hoisted above every private member
   recordSpan(span, sink) {
@@ -4859,11 +4892,57 @@ class ShardDO {
       this.spans.push(span);
     } catch {
     }
-    if (sink?.onSpan) {
-      try {
-        sink.onSpan(span, { waitUntil: this.state.waitUntil?.bind(this.state) });
-      } catch {
-      }
+    if (!sink?.onSpan) {
+      return;
+    }
+    const sampling = this.traceSampling.get(span.traceId);
+    if (sampling && !sampling.sampled) {
+      sampling.sink = sink;
+      return;
+    }
+    this.emitSpan(span, sink);
+  }
+  /**
+   * Hand one span to `sink.onSpan`, swallowing sink throws. The DO's `waitUntil`
+   * is threaded so a network sink (otlpSink) can keep its export alive past the
+   * response, matching the log path. Extracted so both the live-stream path in
+   * {@link recordSpan} and the deferred error-keep flush in
+   * {@link flushSampledOutTrace} share one guarded emit.
+   */
+  emitSpan(span, sink) {
+    if (!sink.onSpan) {
+      return;
+    }
+    try {
+      sink.onSpan(span, { waitUntil: this.state.waitUntil?.bind(this.state) });
+    } catch {
+    }
+  }
+  /**
+   * Export-boundary decision for a sampled-out trace, run from the dispatch
+   * `finally` once the error status is known. A sampled-in trace already
+   * streamed live, so this returns early for it; a sampled-out trace exports its
+   * held `ctx.trace` spans only when `alwaysSampleErrors` is set AND the trace
+   * errored (the dispatch threw, or a held span settled `ok: false`) — the tail
+   * bias — and otherwise drops them. Held spans are read back from the local ring
+   * (excluding the synthetic dispatch root, which never goes to `onSpan`).
+   */
+  flushSampledOutTrace(trace, dispatchFailed) {
+    const sampling = this.traceSampling.get(trace.traceId);
+    if (!sampling || sampling.sampled || !sampling.keepErrors) {
+      return;
+    }
+    const { sink } = sampling;
+    if (!sink?.onSpan) {
+      return;
+    }
+    const held = this.spans.entries().filter((span) => span.traceId === trace.traceId && span.dispatch !== true);
+    const traceHasError = dispatchFailed || held.some((span) => !span.ok);
+    if (!traceHasError) {
+      return;
+    }
+    for (const span of held) {
+      this.emitSpan(span, sink);
     }
   }
   /**

package/dist/packem_shared/{context-telemetry-CqcOObBl.mjs → context-telemetry-BVSDl6PU.mjs}

@@ -49,7 +49,7 @@ const parseTraceparent = (header) => {
   version === "00" && parts.length !== 4 || traceId === void 0 || parentSpanId === void 0 || flags === void 0 || flags.length !== 2 || !HEX_ONLY.test(flags) || traceId.length !== 32 || parentSpanId.length !== 16 || !HEX_ONLY.test(traceId) || !HEX_ONLY.test(parentSpanId) || traceId === "00000000000000000000000000000000" || parentSpanId === "0000000000000000") {
     return void 0;
   }
-  return { parentSpanId, traceId };
+  return { parentSpanId, sampled: (Number.parseInt(flags, 16) & 1) === 1, traceId };
 };
 
 const resolveTraceAnchor = (traceparent) => {
@@ -172,4 +172,4 @@ const dispatchRootSpan = (input) => {
   };
 };
 
-export { createTracer as a, createMetrics as c, dispatchRootSpan as d, normalizeLogFields as n, resolveTraceAnchor as r };
+export { createTracer as a, createMetrics as c, dispatchRootSpan as d, normalizeLogFields as n, parseTraceparent as p, resolveTraceAnchor as r };

package/dist/packem_shared/{createMetrics-Dk4eQ2aJ.mjs → createMetrics-DFADosgV.mjs}

@@ -1 +1 @@
-export { c as createMetrics, a as createTracer, d as dispatchRootSpan } from './context-telemetry-CqcOObBl.mjs';
+export { c as createMetrics, a as createTracer, d as dispatchRootSpan } from './context-telemetry-BVSDl6PU.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/do",
-  "version": "1.0.0-alpha.39",
+  "version": "1.0.0-alpha.40",
   "description": "Lunora Durable Objects: ShardDO (SQLite, OCC, hibernated WebSocket subscriptions) and SessionDO",
   "keywords": [
     "cloudflare",