@dudousxd/nestjs-durable-telescope 0.4.0 → 0.5.0

package/dist/index.cjs

@@ -0,0 +1,763 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DurableTelescopeWatcher: () => DurableTelescopeWatcher,
+  durableDashboard: () => durableDashboard,
+  durableDurationProvider: () => durableDurationProvider,
+  durableRecentFailuresProvider: () => durableRecentFailuresProvider,
+  durableRunsOverTimeProvider: () => durableRunsOverTimeProvider,
+  durableStateBreakdownProvider: () => durableStateBreakdownProvider,
+  durableStateProvider: () => durableStateProvider,
+  durableSuccessRateProvider: () => durableSuccessRateProvider,
+  durableTelescopeExtension: () => durableTelescopeExtension,
+  durableThroughputProvider: () => durableThroughputProvider,
+  durableTimeseriesProvider: () => durableTimeseriesProvider,
+  durableWorkerHealthProvider: () => durableWorkerHealthProvider
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/durable-telescope.watcher.ts
+var import_nestjs_durable_core = require("@dudousxd/nestjs-durable-core");
+var import_api = require("@opentelemetry/api");
+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();
+  register(ctx) {
+    const engine = ctx.moduleRef.get(import_nestjs_durable_core.WorkflowEngine, {
+      strict: false
+    });
+    const tracer = import_api.trace.getTracer("@dudousxd/nestjs-durable-telescope");
+    engine.subscribe((event) => {
+      const record = /* @__PURE__ */ __name(() => ctx.record({
+        type: this.type,
+        content: {
+          event: event.type,
+          workflow: event.workflow,
+          runId: event.runId,
+          seq: event.seq,
+          name: event.name,
+          kind: event.kind,
+          output: event.output,
+          error: event.error,
+          durationMs: event.durationMs
+        },
+        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();
+      if (event.name != null && event.seq != null) {
+        const step = tracer.startSpan(`step ${event.name}`, {
+          attributes: {
+            "durable.run_id": event.runId,
+            "durable.step.seq": event.seq,
+            "durable.step.kind": event.kind
+          }
+        }, base);
+        import_api.context.with(import_api.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);
+      }
+    });
+  }
+  tags(event) {
+    const tags = [
+      "durable",
+      event.type,
+      `run:${event.runId}`
+    ];
+    if (event.workflow) tags.push(`workflow:${event.workflow}`);
+    if (event.kind) tags.push(`kind:${event.kind}`);
+    if (event.type === "run.failed") tags.push("failed");
+    return tags;
+  }
+};
+
+// src/durable-telescope.extension.ts
+var import_nestjs_telescope2 = require("@dudousxd/nestjs-telescope");
+
+// src/durable-dashboard.spec-data.ts
+function durableDashboard(opts = {}) {
+  const runHref = opts.runHref ?? "/durable/runs/{runId}";
+  const windowMs = opts.recentFailuresWindowMs ?? 24 * 60 * 60 * 1e3;
+  return {
+    id: "durable.workflows",
+    label: "Workflows",
+    panels: [],
+    sections: [
+      {
+        title: "Health",
+        cols: 4,
+        panels: [
+          {
+            kind: "gauge",
+            title: "Success rate",
+            data: {
+              provider: "durable.successRate"
+            },
+            max: 1,
+            format: "percent",
+            thresholds: {
+              warn: 0.98,
+              bad: 0.95,
+              direction: "down-bad"
+            }
+          },
+          {
+            kind: "stat",
+            title: "Duration p95",
+            data: {
+              provider: "durable.duration",
+              query: {
+                metric: "p95"
+              }
+            },
+            format: "duration",
+            spark: false,
+            thresholds: {
+              warn: 2e3,
+              bad: 5e3,
+              direction: "up-bad"
+            }
+          },
+          {
+            kind: "stat",
+            title: "Backlog",
+            data: {
+              provider: "durable.state",
+              query: {
+                status: "pending"
+              }
+            },
+            spark: false,
+            thresholds: {
+              warn: 50,
+              bad: 200,
+              direction: "up-bad"
+            }
+          },
+          {
+            kind: "stat",
+            title: "Throughput",
+            data: {
+              provider: "durable.throughput"
+            },
+            format: "rate",
+            spark: true
+          }
+        ]
+      },
+      {
+        title: "Needs attention",
+        cols: 3,
+        panels: [
+          {
+            kind: "topN",
+            title: "Top failing workflows",
+            data: {
+              provider: "durable.timeseries",
+              query: {
+                metric: "topFailures"
+              }
+            },
+            limit: 8
+          },
+          {
+            kind: "table",
+            title: "Stuck runs",
+            data: {
+              provider: "durable.recentFailures",
+              query: {
+                windowMs
+              }
+            },
+            columns: [
+              {
+                key: "updatedAt",
+                label: "Updated"
+              },
+              {
+                key: "workflow",
+                label: "Workflow"
+              },
+              {
+                key: "runId",
+                label: "Run",
+                link: {
+                  href: runHref
+                }
+              },
+              {
+                key: "error",
+                label: "Error"
+              }
+            ]
+          },
+          {
+            kind: "table",
+            title: "Starved worker groups",
+            data: {
+              provider: "durable.workerHealth"
+            },
+            columns: [
+              {
+                key: "group",
+                label: "Group"
+              },
+              {
+                key: "queued",
+                label: "Queued"
+              },
+              {
+                key: "liveWorkers",
+                label: "Workers"
+              },
+              {
+                key: "status",
+                label: "Status"
+              }
+            ]
+          }
+        ]
+      },
+      {
+        title: "Trends",
+        cols: 3,
+        panels: [
+          {
+            kind: "timeseries",
+            title: "Runs over time",
+            data: {
+              provider: "durable.runsOverTime"
+            },
+            series: [
+              "done",
+              "failed"
+            ],
+            style: "stacked"
+          },
+          {
+            kind: "distribution",
+            title: "Duration distribution",
+            data: {
+              provider: "durable.duration"
+            },
+            markers: [
+              "p50",
+              "p95",
+              "p99"
+            ],
+            format: "duration"
+          },
+          {
+            kind: "breakdown",
+            title: "Runs by state",
+            data: {
+              provider: "durable.stateBreakdown"
+            },
+            style: "donut"
+          }
+        ]
+      }
+    ]
+  };
+}
+__name(durableDashboard, "durableDashboard");
+
+// src/durable-data-providers.ts
+var import_nestjs_durable_core2 = require("@dudousxd/nestjs-durable-core");
+var import_nestjs_telescope = require("@dudousxd/nestjs-telescope");
+function percentile(sorted, p) {
+  if (sorted.length === 0) return 0;
+  const idx = Math.min(sorted.length - 1, Math.ceil(p / 100 * sorted.length) - 1);
+  return sorted[Math.max(0, idx)] ?? 0;
+}
+__name(percentile, "percentile");
+async function fetchEntries(ctx) {
+  const storage = ctx.moduleRef.get(import_nestjs_telescope.TELESCOPE_STORAGE, {
+    strict: false
+  });
+  const page = await storage.get({
+    type: "durable",
+    limit: 5e3
+  });
+  return page.data;
+}
+__name(fetchEntries, "fetchEntries");
+function splitWindows(entries, windowMs, now) {
+  const start = now - windowMs;
+  const prevStart = start - windowMs;
+  return {
+    current: entries.filter((e) => {
+      const t = e.createdAt ? +new Date(e.createdAt) : 0;
+      return t > start && t <= now;
+    }),
+    previous: entries.filter((e) => {
+      const t = e.createdAt ? +new Date(e.createdAt) : 0;
+      return t > prevStart && t <= start;
+    })
+  };
+}
+__name(splitWindows, "splitWindows");
+function successRateOf(entries) {
+  let completed = 0;
+  let failed = 0;
+  for (const e of entries) {
+    const c = e.content ?? {};
+    if (c.event === "run.completed") completed += 1;
+    else if (c.event === "run.failed") failed += 1;
+  }
+  const total = completed + failed;
+  return total === 0 ? 1 : completed / total;
+}
+__name(successRateOf, "successRateOf");
+var STATE_CAP = 1e4;
+function durableStateProvider() {
+  return {
+    name: "durable.state",
+    async resolve(query, ctx) {
+      const store = ctx.moduleRef.get(import_nestjs_durable_core2.STATE_STORE, {
+        strict: false
+      });
+      const status = query?.status ?? "dead";
+      const runs = await store.listRuns({
+        status,
+        limit: STATE_CAP
+      });
+      return {
+        value: runs.length
+      };
+    }
+  };
+}
+__name(durableStateProvider, "durableStateProvider");
+function durableTimeseriesProvider() {
+  return {
+    name: "durable.timeseries",
+    async resolve(query, ctx) {
+      const storage = ctx.moduleRef.get(import_nestjs_telescope.TELESCOPE_STORAGE, {
+        strict: false
+      });
+      const limit = Math.min(5e3, Math.max(100, Number(query?.limit ?? 2e3)));
+      const page = await storage.get({
+        type: "durable",
+        limit
+      });
+      let completed = 0;
+      let failed = 0;
+      const failByWorkflow = /* @__PURE__ */ new Map();
+      for (const e of page.data) {
+        const c = e.content ?? {};
+        if (c.event === "run.completed") completed += 1;
+        else if (c.event === "run.failed") {
+          failed += 1;
+          const wf = c.workflow ?? "unknown";
+          failByWorkflow.set(wf, (failByWorkflow.get(wf) ?? 0) + 1);
+        }
+      }
+      const total = completed + failed;
+      const metric = query?.metric ?? "successRate";
+      if (metric === "successRate") return {
+        value: total === 0 ? 1 : completed / total
+      };
+      if (metric === "failed") return {
+        value: failed
+      };
+      if (metric === "total") return {
+        value: total
+      };
+      if (metric === "topFailures") {
+        const items = [
+          ...failByWorkflow.entries()
+        ].map(([label, value]) => ({
+          label,
+          value
+        })).sort((a, b) => b.value - a.value);
+        return {
+          items
+        };
+      }
+      return {
+        value: total
+      };
+    }
+  };
+}
+__name(durableTimeseriesProvider, "durableTimeseriesProvider");
+function durableRecentFailuresProvider() {
+  return {
+    name: "durable.recentFailures",
+    async resolve(query, ctx) {
+      const store = ctx.moduleRef.get(import_nestjs_durable_core2.STATE_STORE, {
+        strict: false
+      });
+      const limit = Math.min(200, Math.max(10, Number(query?.limit ?? 50)));
+      const windowMs = query?.windowMs === void 0 ? 24 * 60 * 60 * 1e3 : Number(query.windowMs);
+      const cutoff = windowMs > 0 ? Date.now() - windowMs : 0;
+      const [failed, dead] = await Promise.all([
+        store.listRuns({
+          status: "failed",
+          limit
+        }),
+        store.listRuns({
+          status: "dead",
+          limit
+        })
+      ]);
+      const rows = [
+        ...failed,
+        ...dead
+      ].filter((r) => +new Date(r.updatedAt) >= cutoff).sort((a, b) => +new Date(b.updatedAt) - +new Date(a.updatedAt)).slice(0, limit).map((r) => ({
+        // Compact UTC stamp ("YYYY-MM-DD HH:mm Z"); the generic table renderer
+        // prints column values as-is, so we format here.
+        updatedAt: `${new Date(r.updatedAt).toISOString().replace("T", " ").slice(0, 16)}Z`,
+        workflow: r.workflow,
+        runId: r.id,
+        error: r.error?.message ?? ""
+      }));
+      return {
+        rows
+      };
+    }
+  };
+}
+__name(durableRecentFailuresProvider, "durableRecentFailuresProvider");
+function durableWorkerHealthProvider() {
+  return {
+    name: "durable.workerHealth",
+    async resolve(query, ctx) {
+      const engine = ctx.moduleRef.get(import_nestjs_durable_core2.WorkflowEngine, {
+        strict: false
+      });
+      const health = await engine.workerHealth();
+      const isStarved = /* @__PURE__ */ __name((g) => g.depth > 0 && g.liveWorkers.length === 0, "isStarved");
+      if (query?.metric === "starvedCount") {
+        return {
+          value: health.filter(isStarved).length
+        };
+      }
+      const rows = health.slice().sort((a, b) => Number(isStarved(b)) - Number(isStarved(a)) || b.depth - a.depth).map((g) => ({
+        group: g.group,
+        queued: g.depth,
+        liveWorkers: g.liveWorkers.length,
+        status: isStarved(g) ? "STARVED" : "ok"
+      }));
+      return {
+        rows
+      };
+    }
+  };
+}
+__name(durableWorkerHealthProvider, "durableWorkerHealthProvider");
+function durableDurationProvider() {
+  return {
+    name: "durable.duration",
+    async resolve(query, ctx) {
+      const entries = await fetchEntries(ctx);
+      const startedAt = /* @__PURE__ */ new Map();
+      for (const e of entries) {
+        const c = e.content ?? {};
+        if (c.event === "run.started" && c.runId && e.createdAt) {
+          startedAt.set(c.runId, +new Date(e.createdAt));
+        }
+      }
+      const durs = [];
+      for (const e of entries) {
+        const c = e.content ?? {};
+        if (c.event === "run.completed" || c.event === "run.failed") {
+          if (typeof c.durationMs === "number") {
+            durs.push(c.durationMs);
+          } else if (c.runId) {
+            const start = startedAt.get(c.runId);
+            const end = e.createdAt ? +new Date(e.createdAt) : void 0;
+            if (start !== void 0 && end !== void 0 && end >= start) {
+              durs.push(end - start);
+            }
+          }
+        }
+      }
+      durs.sort((a, b) => a - b);
+      const p50 = percentile(durs, 50);
+      const p95 = percentile(durs, 95);
+      const p99 = percentile(durs, 99);
+      const metric = query?.metric;
+      if (metric === "p50") return {
+        value: p50
+      };
+      if (metric === "p95") return {
+        value: p95
+      };
+      if (metric === "p99") return {
+        value: p99
+      };
+      const max = durs.at(-1) ?? 0;
+      const bucketCount = 8;
+      const size = Math.max(1, Math.ceil((max + 1) / bucketCount));
+      const buckets = Array.from({
+        length: bucketCount
+      }, (_, i) => ({
+        label: `${Math.round(i * size / 100) / 10}s`,
+        count: 0
+      }));
+      for (const d of durs) {
+        const bi = Math.min(bucketCount - 1, Math.floor(d / size));
+        const bucket = buckets[bi];
+        if (bucket) bucket.count += 1;
+      }
+      return {
+        buckets,
+        p50,
+        p95,
+        p99
+      };
+    }
+  };
+}
+__name(durableDurationProvider, "durableDurationProvider");
+function durableRunsOverTimeProvider() {
+  return {
+    name: "durable.runsOverTime",
+    async resolve(query, ctx) {
+      const entries = await fetchEntries(ctx);
+      const n = Number(query?.buckets ?? 24);
+      const now = Date.now();
+      let minT = now;
+      for (const e of entries) {
+        if (e.createdAt) {
+          const t = +new Date(e.createdAt);
+          if (t < minT) minT = t;
+        }
+      }
+      const span = Math.max(now - minT, 1);
+      const bucketSize = span / n;
+      const rows = Array.from({
+        length: n
+      }, (_, i) => {
+        const bucketStart = new Date(minT + i * bucketSize);
+        const label = bucketStart.toISOString().slice(11, 16);
+        return {
+          label,
+          done: 0,
+          failed: 0
+        };
+      });
+      for (const e of entries) {
+        const c = e.content ?? {};
+        if (c.event !== "run.completed" && c.event !== "run.failed") continue;
+        const t = e.createdAt ? +new Date(e.createdAt) : 0;
+        const idx = Math.min(n - 1, Math.floor((t - minT) / bucketSize));
+        const row = rows[idx];
+        if (row) {
+          if (c.event === "run.completed") row.done += 1;
+          else row.failed += 1;
+        }
+      }
+      return {
+        rows
+      };
+    }
+  };
+}
+__name(durableRunsOverTimeProvider, "durableRunsOverTimeProvider");
+function durableSuccessRateProvider() {
+  return {
+    name: "durable.successRate",
+    async resolve(query, ctx) {
+      const entries = await fetchEntries(ctx);
+      const windowMs = Number(query?.windowMs ?? 24 * 60 * 60 * 1e3);
+      const now = Date.now();
+      const { current, previous } = splitWindows(entries, windowMs, now);
+      const value = successRateOf(current);
+      const prevRate = successRateOf(previous);
+      const delta = previous.length > 0 ? value - prevRate : void 0;
+      const sparkBuckets = 8;
+      const bucketSize = windowMs / sparkBuckets;
+      const sparkStart = now - windowMs;
+      const spark = Array.from({
+        length: sparkBuckets
+      }, (_, i) => {
+        const bStart = sparkStart + i * bucketSize;
+        const bEnd = bStart + bucketSize;
+        const bEntries = current.filter((e) => {
+          const t = e.createdAt ? +new Date(e.createdAt) : 0;
+          return t > bStart && t <= bEnd;
+        });
+        return successRateOf(bEntries);
+      });
+      return {
+        value,
+        delta,
+        spark
+      };
+    }
+  };
+}
+__name(durableSuccessRateProvider, "durableSuccessRateProvider");
+function durableThroughputProvider() {
+  return {
+    name: "durable.throughput",
+    async resolve(query, ctx) {
+      const entries = await fetchEntries(ctx);
+      const windowMs = Number(query?.windowMs ?? 24 * 60 * 60 * 1e3);
+      const now = Date.now();
+      const { current, previous } = splitWindows(entries, windowMs, now);
+      const countCompleted = /* @__PURE__ */ __name((es) => es.filter((e) => (e.content ?? {}).event === "run.completed").length, "countCompleted");
+      const windowHours = windowMs / (60 * 60 * 1e3);
+      const value = countCompleted(current) / windowHours;
+      const prevValue = countCompleted(previous) / windowHours;
+      const delta = previous.length > 0 ? value - prevValue : void 0;
+      const sparkBuckets = 8;
+      const bucketSize = windowMs / sparkBuckets;
+      const bucketHours = bucketSize / (60 * 60 * 1e3);
+      const sparkStart = now - windowMs;
+      const spark = Array.from({
+        length: sparkBuckets
+      }, (_, i) => {
+        const bStart = sparkStart + i * bucketSize;
+        const bEnd = bStart + bucketSize;
+        const bEntries = current.filter((e) => {
+          const t = e.createdAt ? +new Date(e.createdAt) : 0;
+          return t > bStart && t <= bEnd;
+        });
+        return countCompleted(bEntries) / bucketHours;
+      });
+      return {
+        value,
+        delta,
+        spark
+      };
+    }
+  };
+}
+__name(durableThroughputProvider, "durableThroughputProvider");
+var STATE_BREAKDOWN_PALETTE = [
+  "#34d399",
+  "#fbbf24",
+  "#f87171",
+  "#38bdf8",
+  "#a78bfa"
+];
+var STATE_BREAKDOWN_STATUSES = [
+  "running",
+  "pending",
+  "completed",
+  "failed",
+  "dead"
+];
+function durableStateBreakdownProvider() {
+  return {
+    name: "durable.stateBreakdown",
+    async resolve(_query, ctx) {
+      const store = ctx.moduleRef.get(import_nestjs_durable_core2.STATE_STORE, {
+        strict: false
+      });
+      const counts = await Promise.all(STATE_BREAKDOWN_STATUSES.map((status) => store.listRuns({
+        status,
+        limit: STATE_CAP
+      }).then((runs) => runs.length)));
+      const segments = STATE_BREAKDOWN_STATUSES.map((label, i) => ({
+        label,
+        value: counts[i],
+        color: STATE_BREAKDOWN_PALETTE[i]
+      }));
+      return {
+        segments
+      };
+    }
+  };
+}
+__name(durableStateBreakdownProvider, "durableStateBreakdownProvider");
+
+// src/durable-telescope.extension.ts
+function durableTelescopeExtension(opts = {}) {
+  return (0, import_nestjs_telescope2.defineTelescopeExtension)({
+    name: "durable",
+    watchers: /* @__PURE__ */ __name(() => [
+      new DurableTelescopeWatcher()
+    ], "watchers"),
+    entryTypes: /* @__PURE__ */ __name(() => [
+      {
+        id: "durable",
+        label: "Workflows",
+        dot: "bg-amber-400"
+      }
+    ], "entryTypes"),
+    dashboards: /* @__PURE__ */ __name(() => [
+      durableDashboard(opts)
+    ], "dashboards"),
+    dataProviders: /* @__PURE__ */ __name(() => [
+      durableStateProvider(),
+      durableTimeseriesProvider(),
+      durableRecentFailuresProvider(),
+      durableWorkerHealthProvider(),
+      durableDurationProvider(),
+      durableRunsOverTimeProvider(),
+      durableSuccessRateProvider(),
+      durableThroughputProvider(),
+      durableStateBreakdownProvider()
+    ], "dataProviders")
+  });
+}
+__name(durableTelescopeExtension, "durableTelescopeExtension");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DurableTelescopeWatcher,
+  durableDashboard,
+  durableDurationProvider,
+  durableRecentFailuresProvider,
+  durableRunsOverTimeProvider,
+  durableStateBreakdownProvider,
+  durableStateProvider,
+  durableSuccessRateProvider,
+  durableTelescopeExtension,
+  durableThroughputProvider,
+  durableTimeseriesProvider,
+  durableWorkerHealthProvider
+});
+//# sourceMappingURL=index.cjs.map