@lunora/do 1.0.0-alpha.33 → 1.0.0-alpha.35

package/dist/index.mjs

@@ -3,6 +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-DWfYDxCS.mjs';
 export { NotUniqueError, assertValidClientId, createShardCtxDb, normalizeIdStructurally } from './packem_shared/NotUniqueError-Ca21uDuU.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';
@@ -11,7 +12,7 @@ export { diffExternalSource } from './packem_shared/diffExternalSource-CovHfdyo.
 export { materializeExternalRows, materializeExternalRowsIncremental, readExternalSourceBaseline, runExternalSourceTick } from './packem_shared/materializeExternalRows-DlQWMlw_.mjs';
 export { isSoftDeleted, isSourceDue, liftSourceId, pullExternalSourceIncrementalTick, pullExternalSourceTick } from './packem_shared/isSoftDeleted-YLKR6JYw.mjs';
 export { FUNCTION_METRICS_BUCKETS_TABLE, FUNCTION_METRICS_BUCKET_MS, FUNCTION_METRICS_BUCKET_RETENTION, FUNCTION_METRICS_INDEX_TABLE, FUNCTION_METRICS_TABLE, ensureFunctionMetricsTables, readFunctionMetricBuckets, readFunctionMetricIndexHits, readFunctionMetrics, readFunctionMetricsTotals, recordFunctionMetric } from './packem_shared/FUNCTION_METRICS_BUCKETS_TABLE-UDNVD7FS.mjs';
-export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, FLAGS_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, facetColumn, listTables, readTablePage, selectMatchingIds } from './packem_shared/ADMIN_FUNCTIONS-CAHLZMj8.mjs';
+export { ADMIN_FUNCTIONS, ADMIN_FUNCTION_PREFIX, FLAGS_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, facetColumn, listTables, readTablePage, selectMatchingIds } from './packem_shared/ADMIN_FUNCTIONS-CqVmUVNs.mjs';
 export { LogBuffer } from './packem_shared/LogBuffer-B_Ezju_N.mjs';
 export { MAIL_RETENTION, MAIL_TABLE, clearCapturedMail, ensureMailTable, readCapturedMail, recordCapturedMail } from './packem_shared/MAIL_RETENTION-CPpgl-dX.mjs';
 export { default as NotFoundError } from './packem_shared/NotFoundError-C70b9hLw.mjs';
@@ -19,14 +20,14 @@ export { armRestore, readBookmark } from './packem_shared/armRestore-4Px61hHS.mj
 export { applySelect, buildSeekWhere, decodeCursor, encodeCursor, normalizeOrderKeys, softDeleteScope } from './packem_shared/applySelect-WQY8m62C.mjs';
 export { RANK_TIEBREAK, encodePartitionKey, matchesRankStaticWhere, rankTableName, resolveRankPartition, sortColumnName } from './packem_shared/RANK_TIEBREAK-CXhdcA1o.mjs';
 export { ReactiveCache, reactiveCacheKey } from './packem_shared/ReactiveCache-DnSvbjil.mjs';
-export { serveRelationFanout } from './packem_shared/serveRelationFanout-BgaNg3Hu.mjs';
+export { serveRelationFanout } from './packem_shared/serveRelationFanout-Yiyx2OQB.mjs';
 export { DEFAULT_MAX_RELATION_KEYS, assertFlatPredicate, assertShapeShardable, containsRelationPredicate, isRelationPredicate, resolveRelationPredicates } from './packem_shared/DEFAULT_MAX_RELATION_KEYS-BEan1CRD.mjs';
 export { applyOnDelete, fanOutScalarCounts, resolveWith, runRowValidators } from './packem_shared/applyOnDelete-BXSq3S70.mjs';
 export { RLS_UNWRAP_SYMBOL, RlsRequiredError, guardWriter } from './packem_shared/RLS_UNWRAP_SYMBOL-DTvHvRzY.mjs';
 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-afQHUhyA.mjs';
+export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO } from './packem_shared/ROOT_DO_SIZE_WARN_BYTES-QSOI2hpe.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/{ADMIN_FUNCTIONS-CAHLZMj8.mjs → ADMIN_FUNCTIONS-CqVmUVNs.mjs}

@@ -24,6 +24,7 @@ const ADMIN_FUNCTIONS = {
   getFanoutMetrics: "__lunora_admin__:getFanoutMetrics",
   getFunctionStats: "__lunora_admin__:getFunctionStats",
   getIssues: "__lunora_admin__:getIssues",
+  getMetricSeries: "__lunora_admin__:getMetricSeries",
   listSubscriptions: "__lunora_admin__:listSubscriptions",
   listTableIndexes: "__lunora_admin__:listTableIndexes",
   getLogs: "__lunora_admin__:getLogs",
@@ -33,6 +34,7 @@ const ADMIN_FUNCTIONS = {
   getRequestLog: "__lunora_admin__:getRequestLog",
   getSecurityAudit: "__lunora_admin__:getSecurityAudit",
   getSettings: "__lunora_admin__:getSettings",
+  getTraces: "__lunora_admin__:getTraces",
   // eslint-disable-next-line no-secrets/no-secrets -- reserved admin RPC path constant, not a credential
   getWorkflowInstanceStatus: "__lunora_admin__:getWorkflowInstanceStatus",
   importShard: "__lunora_admin__:importShard",

package/dist/packem_shared/{ROOT_DO_SIZE_WARN_BYTES-afQHUhyA.mjs → ROOT_DO_SIZE_WARN_BYTES-QSOI2hpe.mjs}

@@ -5,12 +5,14 @@ import { j as jsonResponse } from './json-response-BdbtpOhm.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-DWfYDxCS.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';
-import { createFanoutCounters, ADMIN_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, selectMatchingIds, ADMIN_FUNCTIONS, findStorageReferences, listTables, summarizeSubscriptions, summarizeFanoutTopics, readTablePage, facetColumn, FLAGS_FUNCTION_PREFIX, recordFanoutPass, MAX_PAGE_SIZE } from './ADMIN_FUNCTIONS-CAHLZMj8.mjs';
+import { createFanoutCounters, ADMIN_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, selectMatchingIds, ADMIN_FUNCTIONS, findStorageReferences, listTables, summarizeSubscriptions, summarizeFanoutTopics, readTablePage, facetColumn, FLAGS_FUNCTION_PREFIX, recordFanoutPass, MAX_PAGE_SIZE } from './ADMIN_FUNCTIONS-CqVmUVNs.mjs';
 import { LogBuffer } from './LogBuffer-B_Ezju_N.mjs';
 import { recordCapturedMail, clearCapturedMail, readCapturedMail, MAIL_TABLE } from './MAIL_RETENTION-CPpgl-dX.mjs';
+import { stableStringify } from './stableStringify-mC40mZts.mjs';
 import { readBookmark, armRestore } from './armRestore-4Px61hHS.mjs';
 import { ReactiveCache, reactiveCacheKey } from './ReactiveCache-DnSvbjil.mjs';
 import { stableWireKey } from './stableWireKey-DKuXO7T5.mjs';
@@ -22,7 +24,6 @@ import { runReadonlySql } from './MAX_SQL_ROWS-iFAA8FbD.mjs';
 import { ConflictError } from './ConflictError-CLoq37xH.mjs';
 import { e as deleteGlobalShapeSnapshotsForConnection, g as readIdempotent, h as writeIdempotent, t as trimIdempotent, r as readClientWatermark, m as migrateClientWatermark, c as advanceClientWatermark, d as deleteGlobalShapeSnapshot, f as readGlobalShapeSnapshot, w as writeGlobalShapeSnapshot } from './ctx-db-idempotency-BdcNpvY4.mjs';
 import { CDC_LOG_TABLE, readCdcChanges, readCdcCursor, readCdcEpoch, minCdcSeq, bumpCdcEpoch } from './CDC_LOG_TABLE-uwOJxJJZ.mjs';
-import { stableStringify } from './stableStringify-mC40mZts.mjs';
 import { a as selectShapeMemberIds, s as selectShapeRows } from './ctx-db-shapes-Cz9dHyh1.mjs';
 
 const MAX_BATCH_ENTRIES = 500;
@@ -182,6 +183,71 @@ const buildBatchEntryRequest = (batchRequest, entry) => {
   });
 };
 
+const DEFAULT_CAPACITY$1 = 256;
+const seriesKey = (event) => `${event.kind}\0${event.name}\0${stableStringify(event.attributes ?? {})}`;
+class MetricBuffer {
+  capacity;
+  series = /* @__PURE__ */ new Map();
+  constructor(capacity = DEFAULT_CAPACITY$1) {
+    this.capacity = capacity > 0 ? Math.trunc(capacity) : DEFAULT_CAPACITY$1;
+  }
+  /** Number of distinct series currently aggregated. */
+  get size() {
+    return this.series.size;
+  }
+  /** Drop every aggregated series. */
+  clear() {
+    this.series.clear();
+  }
+  /**
+   * Snapshot of the aggregated series, most-recently-updated first, each a fresh
+   * copy so a caller can't mutate the live aggregate. `series` is kept in
+   * update order (tail = newest), so one reverse yields newest-first.
+   */
+  entries() {
+    return [...this.series.values()].toReversed().map((s) => {
+      return { ...s };
+    });
+  }
+  /** Fold one measurement into its series, creating or updating the aggregate. */
+  push(event) {
+    const key = seriesKey(event);
+    const existing = this.series.get(key);
+    if (existing === void 0) {
+      if (this.series.size >= this.capacity) {
+        const oldest = this.series.keys().next().value;
+        if (oldest !== void 0) {
+          this.series.delete(oldest);
+        }
+      }
+      this.series.set(key, {
+        ...event.attributes === void 0 ? {} : { attributes: event.attributes },
+        count: 1,
+        firstTs: event.ts,
+        functionPath: event.functionPath,
+        kind: event.kind,
+        last: event.value,
+        lastTs: event.ts,
+        max: event.value,
+        min: event.value,
+        name: event.name,
+        ...event.shardKey === void 0 ? {} : { shardKey: event.shardKey },
+        sum: event.value
+      });
+      return;
+    }
+    this.series.delete(key);
+    existing.count += 1;
+    existing.sum += event.value;
+    existing.min = Math.min(existing.min, event.value);
+    existing.max = Math.max(existing.max, event.value);
+    existing.last = event.value;
+    existing.lastTs = event.ts;
+    existing.functionPath = event.functionPath;
+    this.series.set(key, existing);
+  }
+}
+
 const QUERY_METRICS_TABLE = "__lunora_metrics_queries";
 const QUERY_METRICS_MAX_SQL_LEN = 512;
 const QUERY_METRICS_MAX_STATEMENTS = 500;
@@ -1271,18 +1337,40 @@ const renderLogMessage = (args) => args.map((value) => {
     return String(value);
   }
 }).join(" ");
+const isLogFields = (value) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+};
+const parseLogArgs = (args, boundFields) => {
+  if (args.length === 2 && typeof args[0] === "string" && isLogFields(args[1])) {
+    return { fields: normalizeLogFields(args[1], boundFields), message: args[0] };
+  }
+  return { fields: normalizeLogFields(void 0, boundFields), message: renderLogMessage(args) };
+};
 const emitLogEvent = (input) => {
-  const line = JSON.stringify({
+  const payload = {
+    fields: input.fields,
     function: input.functionPath,
     level: input.level,
     message: input.message,
     shard: input.shardKey,
     source: REQUEST_LOG_EVENT_SOURCE,
+    spanId: input.spanId,
+    traceId: input.traceId,
     ts: input.ts,
     type: LOG_EVENT_TYPE,
     userId: input.userId
-  });
-  if (input.level === "error") {
+  };
+  let line;
+  try {
+    line = JSON.stringify(payload);
+  } catch {
+    line = JSON.stringify({ ...payload, fields: void 0 });
+  }
+  if (input.level === "error" || input.level === "fatal") {
     console.error(line);
   } else if (input.level === "warn") {
     console.warn(line);
@@ -1428,6 +1516,136 @@ const runSocketPool = async (items, processOne, concurrency = 8) => {
   await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, () => worker()));
 };
 
+const DEFAULT_CAPACITY = 500;
+class SpanBuffer {
+  buffer = [];
+  capacity;
+  constructor(capacity = DEFAULT_CAPACITY) {
+    this.capacity = capacity > 0 ? Math.trunc(capacity) : DEFAULT_CAPACITY;
+  }
+  /** Number of spans currently buffered. */
+  get size() {
+    return this.buffer.length;
+  }
+  /** Drop every buffered span. */
+  clear() {
+    this.buffer.length = 0;
+  }
+  /** Snapshot of the buffered spans in insertion order. Fresh array per call. */
+  entries() {
+    return [...this.buffer];
+  }
+  /**
+   * Whether any buffered span belongs to `traceId`. A membership test rather
+   * than `entries().some(...)` so the per-dispatch check that decides whether
+   * to record a root span doesn't copy the whole ring on every request.
+   */
+  hasTrace(traceId) {
+    return this.buffer.some((span) => span.traceId === traceId);
+  }
+  /** Append a span, evicting the oldest when at capacity. */
+  push(span) {
+    this.buffer.push(span);
+    if (this.buffer.length > this.capacity) {
+      this.buffer.shift();
+    }
+  }
+}
+const DEFAULT_TRACE_LIMIT = 50;
+const groupByTrace = (spans) => {
+  const byTrace = /* @__PURE__ */ new Map();
+  for (const span of spans) {
+    const group = byTrace.get(span.traceId);
+    if (group === void 0) {
+      byTrace.set(span.traceId, [span]);
+    } else {
+      group.push(span);
+    }
+  }
+  return byTrace;
+};
+const selectAnchor = (group, byId) => {
+  const declaredRoot = group.find((span) => span.dispatch === true);
+  if (declaredRoot !== void 0) {
+    return declaredRoot;
+  }
+  const byStart = group.toSorted((a, b) => a.startTs - b.startTs);
+  return byStart.find((span) => !byId.has(span.parentSpanId)) ?? byStart[0];
+};
+const depthResolver = (anchor, byId) => {
+  const cache = /* @__PURE__ */ new Map([[anchor.spanId, 0]]);
+  return (span) => {
+    const chain = [];
+    const seen = /* @__PURE__ */ new Set();
+    let current = span;
+    let base = 0;
+    for (; ; ) {
+      const known = cache.get(current.spanId);
+      if (known !== void 0) {
+        base = known;
+        break;
+      }
+      if (seen.has(current.spanId)) {
+        break;
+      }
+      seen.add(current.spanId);
+      chain.push(current);
+      const parent = byId.get(current.parentSpanId);
+      if (parent === void 0) {
+        break;
+      }
+      current = parent;
+    }
+    for (const [index, entry] of chain.toReversed().entries()) {
+      cache.set(entry.spanId, base + index + 1);
+    }
+    return cache.get(span.spanId) ?? base;
+  };
+};
+const foldTraces = (spans, limit = DEFAULT_TRACE_LIMIT) => {
+  const byTrace = groupByTrace(spans);
+  const selected = [...byTrace.entries()].map(([traceId, group]) => {
+    return { group, startTs: Math.min(...group.map((span) => span.startTs)), traceId };
+  }).toSorted((a, b) => b.startTs - a.startTs).slice(0, limit);
+  const summaries = [];
+  for (const { group, traceId } of selected) {
+    const byId = new Map(group.map((span) => [span.spanId, span]));
+    const anchor = selectAnchor(group, byId);
+    if (anchor === void 0) {
+      continue;
+    }
+    const depthOf = depthResolver(anchor, byId);
+    const { startTs } = anchor;
+    const endTs = Math.max(...group.map((span) => span.startTs + span.durationMs));
+    const rows = group.map((span) => {
+      return {
+        ...span.attributes === void 0 ? {} : { attributes: span.attributes },
+        depth: depthOf(span),
+        durationMs: span.durationMs,
+        ...span.error === void 0 ? {} : { error: span.error },
+        name: span.name,
+        // Clamped at 0: a child whose parent was evicted can predate the
+        // anchor, and a negative offset would render as a bar off-canvas.
+        offsetMs: Math.max(0, span.startTs - startTs),
+        ok: span.ok,
+        parentSpanId: span.parentSpanId,
+        spanId: span.spanId
+      };
+    }).toSorted((a, b) => a.offsetMs - b.offsetMs || a.depth - b.depth);
+    summaries.push({
+      durationMs: endTs - startTs,
+      functionPath: anchor.functionPath,
+      ok: group.every((span) => span.ok),
+      rootName: anchor.name,
+      ...anchor.shardKey === void 0 ? {} : { shardKey: anchor.shardKey },
+      spans: rows,
+      startTs,
+      traceId
+    });
+  }
+  return { total: byTrace.size, traces: summaries.toSorted((a, b) => b.startTs - a.startTs) };
+};
+
 const DANGLING_SCAN_CAP = 5e3;
 const DANGLING_RESULT_CAP = 500;
 const DOC_COLUMN = "__doc__";
@@ -2164,6 +2382,14 @@ class ShardDO {
   currentRequestIp;
   /** W3C `traceparent` of the inbound RPC; forwarded onto outbound container fetches. */
   currentRequestTraceparent;
+  /**
+   * Trace ids for the in-flight dispatch, resolved once at entry (see
+   * {@link resolveTraceAnchor}). Shared by `ctx.trace` and by the synthetic
+   * root span recorded on the way out so both agree even with no inbound
+   * `traceparent`. Cleared in the same `finally` as the other per-request
+   * fields.
+   */
+  currentRequestTrace;
   /**
    * 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
@@ -2361,6 +2587,19 @@ class ShardDO {
    * "recent RPC errors on this instance" feed, not a general application log.
    */
   logs = new LogBuffer();
+  /**
+   * Recent `ctx.trace` spans (plus the synthetic per-dispatch root), powering
+   * the studio's Traces panel. In-memory and hibernation-volatile like
+   * `logs` — production tracing ships to a collector via `otlpSink`.
+   */
+  spans = new SpanBuffer();
+  /**
+   * Running aggregates of `ctx.metrics.*` measurements, powering the studio's
+   * Metrics panel. In-memory and hibernation-volatile like `logs` and
+   * `spans`, but folds samples into per-series totals rather than ringing
+   * raw events — production aggregation ships to a collector via the sink.
+   */
+  metricSeries = new MetricBuffer();
   /**
    * In-flight dependency tracker for the currently-executing query. Set by
    * `runCachedQuery` so the ctx-db hooks (wired via `onRead`) can
@@ -2452,6 +2691,7 @@ class ShardDO {
    * Worker-side fetch entry point. Handles WebSocket upgrades and the
    * shard-local RPC endpoint forwarded by `@lunora/runtime`.
    */
+  // eslint-disable-next-line sonarjs/cognitive-complexity -- the DO's central request router; #149 added the trace-anchor capture and root-span record, tipping it to 16. Splitting the request lifecycle across helpers would hurt readability more than the +1 costs.
   async fetch(request) {
     const url = new URL(request.url);
     this.shardBinding = request.headers.get("x-lunora-shard-binding") ?? this.shardBinding;
@@ -2483,6 +2723,8 @@ class ShardDO {
     this.currentRequestIp = request.headers.get("x-lunora-client-ip") ?? void 0;
     this.currentRequestSystem = request.headers.get("x-lunora-system") === "1";
     this.currentRequestTraceparent = request.headers.get("traceparent") ?? void 0;
+    this.currentRequestTrace = resolveTraceAnchor(this.currentRequestTraceparent);
+    const dispatchTrace = this.currentRequestTrace;
     this.currentRequestReadTables = void 0;
     this.currentRequestCacheHit = void 0;
     this.metrics.requests += 1;
@@ -2490,6 +2732,7 @@ class ShardDO {
     this.currentScannedTables = /* @__PURE__ */ new Set();
     this.currentIndexHits = /* @__PURE__ */ new Set();
     this.currentStmtSamples = [];
+    let dispatchError;
     try {
       if (payload.functionPath.startsWith(RELATION_FUNCTION_PREFIX)) {
         const value = await this.runRelationFanoutRead(payload.functionPath, payload.args ?? {});
@@ -2521,6 +2764,7 @@ class ShardDO {
       return response;
     } catch (error) {
       this.metrics.errors += 1;
+      dispatchError = { thrown: error };
       const durationMs = Date.now() - dispatchStartedAt;
       const message = error instanceof Error ? error.message : String(error);
       const conflicted = error instanceof ConflictError && error.kind === "occ";
@@ -2540,6 +2784,10 @@ class ShardDO {
       await this.flushChangedTables();
       return this.errorToResponse(error);
     } finally {
+      if (this.spans.hasTrace(dispatchTrace.traceId)) {
+        this.recordDispatchRootSpan(payload.functionPath, dispatchStartedAt, dispatchError, dispatchTrace);
+      }
+      this.currentRequestTrace = void 0;
       this.currentRequestBookmark = void 0;
       this.currentResponseBookmark = void 0;
       this.currentRequestUserId = void 0;
@@ -3009,6 +3257,14 @@ class ShardDO {
   getCurrentTraceparent() {
     return this.currentRequestTraceparent;
   }
+  /**
+   * The in-flight dispatch's trace ids, for the generated `buildCtx` to hand to
+   * {@link makeTracer}. `undefined` outside a dispatch (an alarm, a lifecycle
+   * hook), where the tracer mints its own anchor.
+   */
+  getCurrentTrace() {
+    return this.currentRequestTrace;
+  }
   /**
    * Identity claims (email, name, roles, …) forwarded by the runtime's
    * `resolveIdentity` hook. Returns `undefined` for anonymous requests
@@ -4082,24 +4338,173 @@ class ShardDO {
    * Unlike request-log args, `ctx.log` args are NOT redacted: the developer
    * chose to log them, exactly like a raw `console.log`.
    */
-  recordUserLog(functionPath, level, args, sink) {
+  recordUserLog(functionPath, level, args, message, fields, sink) {
+    const trace = this.currentRequestTrace;
     const event = {
       args,
+      fields,
       functionPath,
       level,
-      message: renderLogMessage(args),
+      message,
       shardKey: this.state.id?.name,
+      spanId: trace?.rootSpanId,
+      traceId: trace?.traceId,
       ts: Date.now(),
       userId: this.getCurrentUserId()
     };
-    this.logs.push({ functionPath, level: level === "log" ? "info" : level, message: event.message, timestamp: event.ts });
+    this.logs.push({ fields, functionPath, level, message, timestamp: event.ts });
     try {
       emitLogEvent(event);
     } catch {
     }
     if (sink?.onLog) {
       try {
-        sink.onLog(event);
+        sink.onLog(event, { waitUntil: this.state.waitUntil?.bind(this.state) });
+      } catch {
+      }
+    }
+  }
+  /**
+   * Build the `ctx.log` logger for one dispatched function. Each severity method
+   * accepts either the structured form (`(message, fields)`) or console-style
+   * varargs (see {@link parseLogArgs}); `with(fields)` returns a child that
+   * stamps `fields` onto every line. The generated `buildCtx` calls this once
+   * per dispatch and assigns the result to `ctx.log`.
+   */
+  makeLogger(functionPath, sink, boundFields) {
+    const emit = (level, args) => {
+      const { fields, message } = parseLogArgs(args, boundFields);
+      this.recordUserLog(functionPath, level, args, message, fields, sink);
+    };
+    return {
+      debug: (...args) => {
+        emit("debug", args);
+      },
+      error: (...args) => {
+        emit("error", args);
+      },
+      fatal: (...args) => {
+        emit("fatal", args);
+      },
+      info: (...args) => {
+        emit("info", args);
+      },
+      log: (...args) => {
+        emit("log", args);
+      },
+      trace: (...args) => {
+        emit("trace", args);
+      },
+      warn: (...args) => {
+        emit("warn", args);
+      },
+      with: (fields) => this.makeLogger(functionPath, sink, boundFields ? { ...boundFields, ...fields } : fields)
+    };
+  }
+  /**
+   * Build the `ctx.trace` span factory for one dispatched function. The
+   * generated `buildCtx` calls this once per dispatch and assigns the result to
+   * `ctx.trace`.
+   *
+   * Thin wiring over {@link createTracer}, which owns the span semantics (see
+   * there for why nesting is explicit rather than ambient). Everything it needs
+   * from the shard is passed explicitly.
+   *
+   * `anchor` is the trace this ctx's spans belong to; omit it for a ctx with no
+   * owning dispatch (an alarm, a subscription re-run) to mint a fresh anchor, so
+   * `ctx.trace` still yields a coherent self-contained trace there.
+   */
+  makeTracer(functionPath, sink, anchor) {
+    return createTracer({
+      anchor: anchor ?? resolveTraceAnchor(void 0),
+      functionPath,
+      record: (span) => {
+        this.recordSpan(span, sink);
+      },
+      shardKey: this.state.id?.name,
+      userId: () => this.getCurrentUserId()
+    });
+  }
+  /**
+   * Build the `ctx.metrics` recorder for one dispatched function. Thin wiring
+   * over {@link createMetrics}, which owns the instrument semantics.
+   */
+  makeMetrics(functionPath, sink) {
+    return createMetrics({
+      functionPath,
+      record: (event) => {
+        this.recordMetric(event, sink);
+      },
+      shardKey: this.state.id?.name
+    });
+  }
+  /**
+   * Fold one measurement into the in-memory {@link metricSeries} readout and
+   * hand it to the optional `sink.onMetric`. Best-effort like
+   * {@link recordUserLog} and {@link recordSpan}: recording a measurement must
+   * never break the handler that recorded it.
+   *
+   * The buffer folds rather than rings: a measurement's value is in its
+   * aggregate over a window, which a bounded ring of raw samples can't represent
+   * (it evicts the oldest samples, the ones a running total needs). So the
+   * buffer keeps one running aggregate per series and resets on hibernation like
+   * logs and spans — a "recent metrics on this instance" dev readout. Durable,
+   * cross-instance aggregation is still the sink's job.
+   */
+  recordMetric(event, sink) {
+    try {
+      this.metricSeries.push(event);
+    } catch {
+    }
+    if (sink?.onMetric) {
+      try {
+        sink.onMetric(event, { waitUntil: this.state.waitUntil?.bind(this.state) });
+      } catch {
+      }
+    }
+  }
+  /**
+   * Buffer the synthetic root span for a finished dispatch. The caller gates
+   * this on the dispatch having actually produced spans (the `hasTrace` check at
+   * the call site): every request minting a root would fill the bounded ring
+   * with single-bar traces from uninstrumented handlers and evict the
+   * instrumented ones the panel exists to show.
+   *
+   * `anchor` carries the dispatch's trace ids, captured at entry rather than
+   * read from `this` here — this runs after the handler's awaits, where the
+   * shared field may already belong to an interleaved dispatch.
+   */
+  recordDispatchRootSpan(functionPath, startedAt, failure, anchor) {
+    try {
+      this.spans.push(
+        dispatchRootSpan({
+          anchor,
+          durationMs: Date.now() - startedAt,
+          failure,
+          functionPath,
+          shardKey: this.state.id?.name,
+          startTs: startedAt,
+          userId: this.getCurrentUserId()
+        })
+      );
+    } catch {
+    }
+  }
+  /**
+   * Buffer one span for the studio Traces panel and hand it to the optional
+   * `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.
+   */
+  // 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) {
+    try {
+      this.spans.push(span);
+    } catch {
+    }
+    if (sink?.onSpan) {
+      try {
+        sink.onSpan(span, { waitUntil: this.state.waitUntil?.bind(this.state) });
       } catch {
       }
     }
@@ -5179,6 +5584,7 @@ class ShardDO {
    * wraps each in the {@link ADMIN_WILDCARD} sentinel, keeping that one fact in
    * a single place and `readAdminOp` under its complexity budget.
    */
+  // eslint-disable-next-line sonarjs/cognitive-complexity -- a flat admin-RPC dispatch chain (one trivial branch per function); #149 added the getTraces/getMetrics branches. A lookup table would obscure the 1:1 path→reader mapping this deliberately keeps.
   readAdminWildcardOp(functionPath) {
     if (functionPath === ADMIN_FUNCTIONS.listTables) {
       return listTables(this.state.storage.sql);
@@ -5198,6 +5604,13 @@ class ShardDO {
     if (functionPath === ADMIN_FUNCTIONS.getLogs) {
       return { entries: this.logs.entries() };
     }
+    if (functionPath === ADMIN_FUNCTIONS.getTraces) {
+      const folded = foldTraces(this.spans.entries());
+      return { total: folded.total, traces: folded.traces };
+    }
+    if (functionPath === ADMIN_FUNCTIONS.getMetricSeries) {
+      return { series: this.metricSeries.entries() };
+    }
     if (functionPath === ADMIN_FUNCTIONS.getSettings) {
       return buildSettings(this.env);
     }