@dudousxd/nestjs-durable-telescope 0.7.2 → 0.8.0

package/dist/index.cjs

@@ -22,8 +22,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   DurableTelescopeWatcher: () => DurableTelescopeWatcher,
+  currentDurableScope: () => currentDurableScope,
   durableDashboard: () => durableDashboard,
   durableDurationProvider: () => durableDurationProvider,
+  durableExecutionScope: () => durableExecutionScope,
   durableRecentFailuresProvider: () => durableRecentFailuresProvider,
   durableRunsOverTimeProvider: () => durableRunsOverTimeProvider,
   durableStateBreakdownProvider: () => durableStateBreakdownProvider,
@@ -32,30 +34,146 @@ __export(index_exports, {
   durableTelescopeExtension: () => durableTelescopeExtension,
   durableThroughputProvider: () => durableThroughputProvider,
   durableTimeseriesProvider: () => durableTimeseriesProvider,
+  durableTraceContext: () => durableTraceContext,
   durableWorkerHealthProvider: () => durableWorkerHealthProvider,
-  durableWorkerStatusProvider: () => durableWorkerStatusProvider
+  durableWorkerStatusProvider: () => durableWorkerStatusProvider,
+  runTraceContext: () => runTraceContext,
+  runTraceId: () => runTraceId
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/durable-telescope.watcher.ts
 var import_nestjs_durable_core = require("@dudousxd/nestjs-durable-core");
+var import_api3 = require("@opentelemetry/api");
+
+// src/durable-execution-scope.ts
+var import_node_async_hooks = require("async_hooks");
+var import_node_crypto2 = require("crypto");
+var import_api2 = require("@opentelemetry/api");
+
+// src/durable-run-trace.ts
+var import_node_crypto = require("crypto");
 var import_api = require("@opentelemetry/api");
+function runTraceId(runId) {
+  return (0, import_node_crypto.createHash)("sha256").update(`durable:run:${runId}`).digest("hex").slice(0, 32);
+}
+__name(runTraceId, "runTraceId");
+function runSpanId(runId) {
+  return (0, import_node_crypto.createHash)("sha256").update(`durable:run-span:${runId}`).digest("hex").slice(0, 16);
+}
+__name(runSpanId, "runSpanId");
+function runTraceContext(runId, parent = import_api.context.active()) {
+  return import_api.trace.setSpanContext(parent, {
+    traceId: runTraceId(runId),
+    spanId: runSpanId(runId),
+    traceFlags: import_api.TraceFlags.SAMPLED,
+    isRemote: true
+  });
+}
+__name(runTraceContext, "runTraceContext");
+
+// src/durable-execution-scope.ts
+var activeScope = new import_node_async_hooks.AsyncLocalStorage();
+function currentDurableScope() {
+  return activeScope.getStore();
+}
+__name(currentDurableScope, "currentDurableScope");
+var DURABLE_BATCH_ORIGIN = "queue";
+function spanName(execution) {
+  if (execution.unit === "step") return `step ${execution.name ?? "?"}`;
+  return `workflow ${execution.workflow ?? "?"}`;
+}
+__name(spanName, "spanName");
+function spanAttributes(execution) {
+  const attributes = {
+    "durable.run_id": execution.runId
+  };
+  if (execution.workflow !== void 0) attributes["durable.workflow"] = execution.workflow;
+  if (execution.name !== void 0) attributes["durable.step.name"] = execution.name;
+  if (execution.seq !== void 0) attributes["durable.step.seq"] = execution.seq;
+  if (execution.attempt !== void 0) attributes["durable.step.attempt"] = execution.attempt;
+  return attributes;
+}
+__name(spanAttributes, "spanAttributes");
+function durableExecutionScope(ctx) {
+  const tracer = import_api2.trace.getTracer("@dudousxd/nestjs-durable-telescope");
+  const owner = {};
+  return (execution, next) => {
+    const open = activeScope.getStore();
+    if (open?.owner === owner && open.runId === execution.runId) return next();
+    if (ctx.config.enabled === false) return next();
+    try {
+      const parent = runTraceContext(execution.runId);
+      const span = tracer.startSpan(spanName(execution), {
+        attributes: spanAttributes(execution)
+      }, parent);
+      const spanContext = span.spanContext();
+      const scope = {
+        runId: execution.runId,
+        traceId: runTraceId(execution.runId),
+        spanId: span.isRecording() ? spanContext.spanId : (0, import_node_crypto2.randomBytes)(8).toString("hex"),
+        owner
+      };
+      return import_api2.context.with(import_api2.trace.setSpan(parent, span), () => activeScope.run(scope, () => ctx.runInBatch(DURABLE_BATCH_ORIGIN, next).then((value) => {
+        span.end();
+        return value;
+      }, (error) => {
+        span.setStatus({
+          code: import_api2.SpanStatusCode.ERROR,
+          ...error instanceof Error ? {
+            message: error.message
+          } : {}
+        });
+        span.end();
+        throw error;
+      })));
+    } catch {
+      return next();
+    }
+  };
+}
+__name(durableExecutionScope, "durableExecutionScope");
+function durableTraceContext(delegate) {
+  return {
+    current() {
+      const fromDelegate = delegate?.current() ?? null;
+      if (fromDelegate) return fromDelegate;
+      const scope = activeScope.getStore();
+      return scope ? {
+        traceId: scope.traceId,
+        spanId: scope.spanId
+      } : null;
+    }
+  };
+}
+__name(durableTraceContext, "durableTraceContext");
+
+// src/durable-telescope.watcher.ts
 var DurableTelescopeWatcher = class {
   static {
     __name(this, "DurableTelescopeWatcher");
   }
   type = "durable";
-  /** Open root span per run, so step entries nest under it and share its traceId. */
-  roots = /* @__PURE__ */ new Map();
+  /** Removes the execution wrapper from the engine's process-level registry. */
+  disposeScope;
   register(ctx) {
+    this.disposeScope?.();
+    this.disposeScope = (0, import_nestjs_durable_core.useDurableExecution)(durableExecutionScope(ctx));
     const engine = ctx.moduleRef.get(import_nestjs_durable_core.WorkflowEngine, {
       strict: false
     });
     if (typeof engine?.subscribe !== "function") return;
-    const tracer = import_api.trace.getTracer("@dudousxd/nestjs-durable-telescope");
+    const tracer = import_api3.trace.getTracer("@dudousxd/nestjs-durable-telescope");
     engine.subscribe((event) => {
       const record = /* @__PURE__ */ __name(() => ctx.record({
         type: this.type,
+        // Stated explicitly rather than left to the ambient span, and the Recorder honours an
+        // explicit `traceId` above everything else. A lifecycle event is very often emitted
+        // OUTSIDE any execution scope — a remote step's result lands in a transport callback, a
+        // recovery sweep emits for a run this process never executed — and those entries are
+        // exactly the ones an operator follows into the trace. We know the run, so we know the
+        // trace; there is no reason to let it depend on where the emit happened to land.
+        traceId: runTraceId(event.runId),
         content: {
           event: event.type,
           workflow: event.workflow,
@@ -69,16 +187,7 @@ var DurableTelescopeWatcher = class {
         },
         tags: this.tags(event)
       }), "record");
-      if (event.type === "run.started") {
-        this.roots.set(event.runId, tracer.startSpan(`workflow ${event.workflow ?? "?"}`, {
-          attributes: {
-            "durable.run_id": event.runId,
-            "durable.workflow": event.workflow
-          }
-        }));
-      }
-      const root = this.roots.get(event.runId);
-      const base = root ? import_api.trace.setSpan(import_api.context.active(), root) : import_api.context.active();
+      const base = runTraceContext(event.runId);
       if (event.name != null && event.seq != null) {
         const step = tracer.startSpan(`step ${event.name}`, {
           attributes: {
@@ -87,27 +196,32 @@ var DurableTelescopeWatcher = class {
             "durable.step.kind": event.kind
           }
         }, base);
-        import_api.context.with(import_api.trace.setSpan(base, step), record);
+        if (event.type === "step.failed") {
+          const message = event.error?.message;
+          step.setStatus(message !== void 0 ? {
+            code: import_api3.SpanStatusCode.ERROR,
+            message
+          } : {
+            code: import_api3.SpanStatusCode.ERROR
+          });
+        }
+        import_api3.context.with(import_api3.trace.setSpan(base, step), record);
         step.end();
       } else {
-        import_api.context.with(base, record);
-      }
-      if (event.type === "run.completed" || event.type === "run.suspended") {
-        root?.end();
-        this.roots.delete(event.runId);
-      } else if (event.type === "run.failed") {
-        const message = event.error?.message;
-        root?.setStatus(message !== void 0 ? {
-          code: import_api.SpanStatusCode.ERROR,
-          message
-        } : {
-          code: import_api.SpanStatusCode.ERROR
-        });
-        root?.end();
-        this.roots.delete(event.runId);
+        import_api3.context.with(base, record);
       }
     });
   }
+  /**
+  * Detach the execution wrapper. The `Watcher` SPI has no teardown hook, so nothing calls this in a
+  * running app — where the wrapper should live exactly as long as the process does. It exists so a
+  * test that registers a watcher does not leave a wrapper behind in the process-level registry for
+  * the next test to trip over.
+  */
+  unregister() {
+    this.disposeScope?.();
+    this.disposeScope = void 0;
+  }
   tags(event) {
     const tags = [
       "durable",
@@ -284,7 +398,10 @@ function durableDashboard(opts = {}) {
             // One row per LIVE worker (flattened from each group's heartbeats), exposing the live
             // WorkerStatus the heartbeat carries: fixed vs. adaptive limit, in-flight saturation,
             // RAM%/CPU%, throughput, p95, and why the adaptive controller last moved. A worker from
-            // an older SDK with no status still lists, with '—' in the measured columns. The
+            // an older SDK with no status still lists, reading 'n/a' — distinct from the '—' of a
+            // worker that reports fine but has nothing to measure yet, which is what an idle
+            // deployment looks like (throughput and p95 come off a rolling window of completions,
+            // so they are empty until a step finishes inside it). The
             // adaptive min–max range rides the In-flight column's row value (`minMax` key) for those
             // that want it; the visible columns stay readable.
             title: "Workers",
@@ -598,17 +715,23 @@ function relAgo(atMs) {
   return `${Math.round(h / 24)}d ago`;
 }
 __name(relAgo, "relAgo");
-function fmtLastAdjust(a) {
-  if (!a) return "\u2014";
+var NOT_REPORTED = "n/a";
+var NOT_YET_MEASURED = "\u2014";
+function fmtLastAdjust(status) {
+  if (!status) return NOT_REPORTED;
+  const a = status.lastAdjust;
+  if (!a) return NOT_YET_MEASURED;
   return `${a.reason} ${a.from}\u2192${a.to} ${relAgo(a.at)}`;
 }
 __name(fmtLastAdjust, "fmtLastAdjust");
-function fmtPct(n) {
-  return typeof n === "number" ? Math.round(n) : "\u2014";
+function fmtPct(n, status) {
+  if (typeof n === "number") return Math.round(n);
+  return status ? NOT_YET_MEASURED : NOT_REPORTED;
 }
 __name(fmtPct, "fmtPct");
-function fmtNum(n) {
-  return typeof n === "number" ? Math.round(n) : "\u2014";
+function fmtNum(n, status) {
+  if (typeof n === "number") return Math.round(n);
+  return status ? NOT_YET_MEASURED : NOT_REPORTED;
 }
 __name(fmtNum, "fmtNum");
 function durableWorkerStatusProvider() {
@@ -622,11 +745,11 @@ function durableWorkerStatusProvider() {
       const rows = health.slice().sort((a, b) => Number(b.depth > 0) - Number(a.depth > 0) || a.group.localeCompare(b.group)).flatMap((group) => group.liveWorkers.slice().sort((a, b) => a.instanceId.localeCompare(b.instanceId)).map((worker) => {
         const status = worker.status;
         const concurrency = status?.concurrency;
-        const mode = concurrency?.mode ?? "\u2014";
-        const limit = concurrency?.limit ?? "\u2014";
-        const inFlight = status?.inFlight ?? "\u2014";
-        const minMax = concurrency?.mode === "adaptive" ? `${concurrency.min ?? 1}\u2013${concurrency.max ?? 32}` : "\u2014";
-        const saturation = concurrency && status ? `${status.inFlight}/${concurrency.limit}` : "\u2014";
+        const mode = concurrency?.mode ?? NOT_REPORTED;
+        const limit = concurrency?.limit ?? NOT_REPORTED;
+        const inFlight = status?.inFlight ?? NOT_REPORTED;
+        const minMax = concurrency?.mode === "adaptive" ? `${concurrency.min ?? 1}\u2013${concurrency.max ?? 32}` : NOT_REPORTED;
+        const saturation = concurrency && status ? `${status.inFlight}/${concurrency.limit}` : NOT_REPORTED;
         return {
           group: group.group,
           instanceId: worker.instanceId,
@@ -636,11 +759,11 @@ function durableWorkerStatusProvider() {
           inFlight,
           saturation,
           queued: group.depth,
-          rssPct: fmtPct(status?.rssPct),
-          cpuPct: fmtPct(status?.cpuPct),
-          throughputPerMin: fmtNum(status?.throughputPerMin),
-          p95Ms: fmtNum(status?.p95Ms),
-          lastAdjust: fmtLastAdjust(status?.lastAdjust)
+          rssPct: fmtPct(status?.rssPct, status),
+          cpuPct: fmtPct(status?.cpuPct, status),
+          throughputPerMin: fmtNum(status?.throughputPerMin, status),
+          p95Ms: fmtNum(status?.p95Ms, status),
+          lastAdjust: fmtLastAdjust(status)
         };
       }));
       return {
@@ -906,8 +1029,10 @@ __name(durableTelescopeExtension, "durableTelescopeExtension");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DurableTelescopeWatcher,
+  currentDurableScope,
   durableDashboard,
   durableDurationProvider,
+  durableExecutionScope,
   durableRecentFailuresProvider,
   durableRunsOverTimeProvider,
   durableStateBreakdownProvider,
@@ -916,7 +1041,10 @@ __name(durableTelescopeExtension, "durableTelescopeExtension");
   durableTelescopeExtension,
   durableThroughputProvider,
   durableTimeseriesProvider,
+  durableTraceContext,
   durableWorkerHealthProvider,
-  durableWorkerStatusProvider
+  durableWorkerStatusProvider,
+  runTraceContext,
+  runTraceId
 });
 //# sourceMappingURL=index.cjs.map