@dudousxd/nestjs-durable-telescope 0.1.0

package/dist/durable-telescope.watcher.d.ts

@@ -0,0 +1,23 @@
+import type { Watcher, WatcherContext } from '@dudousxd/nestjs-telescope';
+/**
+ * A Telescope watcher that turns durable-workflow lifecycle events into Telescope entries, so
+ * runs and steps (including remote/Python steps) show up alongside the app's requests, queries
+ * and jobs in the Telescope UI — under the **Workflows** tab.
+ *
+ * It also **trace-groups** a run: a root span is opened per run and every entry is recorded inside
+ * that span's OTel context (step entries inside a child `step …` span). Telescope's trace-context
+ * provider stamps each entry with the active span, so a whole workflow shows up as a single trace
+ * on the Traces page — run → steps — with each entry carrying the run's `traceId`. When the host has
+ * no OTel SDK the spans are no-ops and entries simply carry no trace (the prior behaviour).
+ *
+ * Add it to `TelescopeModule.forRoot({ watchers: [new DurableTelescopeWatcher()] })`. It resolves
+ * the engine from the (global) durable providers and subscribes to its events.
+ */
+export declare class DurableTelescopeWatcher implements Watcher {
+    readonly type = "durable";
+    /** Open root span per run, so step entries nest under it and share its traceId. */
+    private readonly roots;
+    register(ctx: WatcherContext): void;
+    private tags;
+}
+//# sourceMappingURL=durable-telescope.watcher.d.ts.map

package/dist/durable-telescope.watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-telescope.watcher.d.ts","sourceRoot":"","sources":["../src/durable-telescope.watcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAG1E;;;;;;;;;;;;;GAaG;AACH,qBAAa,uBAAwB,YAAW,OAAO;IACrD,QAAQ,CAAC,IAAI,aAAa;IAC1B,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IAEjD,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IAkEnC,OAAO,CAAC,IAAI;CAOb"}

package/dist/durable-telescope.watcher.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DurableTelescopeWatcher = void 0;
+const nestjs_durable_core_1 = require("@dudousxd/nestjs-durable-core");
+const api_1 = require("@opentelemetry/api");
+/**
+ * A Telescope watcher that turns durable-workflow lifecycle events into Telescope entries, so
+ * runs and steps (including remote/Python steps) show up alongside the app's requests, queries
+ * and jobs in the Telescope UI — under the **Workflows** tab.
+ *
+ * It also **trace-groups** a run: a root span is opened per run and every entry is recorded inside
+ * that span's OTel context (step entries inside a child `step …` span). Telescope's trace-context
+ * provider stamps each entry with the active span, so a whole workflow shows up as a single trace
+ * on the Traces page — run → steps — with each entry carrying the run's `traceId`. When the host has
+ * no OTel SDK the spans are no-ops and entries simply carry no trace (the prior behaviour).
+ *
+ * Add it to `TelescopeModule.forRoot({ watchers: [new DurableTelescopeWatcher()] })`. It resolves
+ * the engine from the (global) durable providers and subscribes to its events.
+ */
+class DurableTelescopeWatcher {
+    type = 'durable';
+    /** Open root span per run, so step entries nest under it and share its traceId. */
+    roots = new Map();
+    register(ctx) {
+        const engine = ctx.moduleRef.get(nestjs_durable_core_1.WorkflowEngine, { strict: false });
+        const tracer = api_1.trace.getTracer('@dudousxd/nestjs-durable-telescope');
+        engine.subscribe((event) => {
+            const record = () => 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,
+                },
+                tags: this.tags(event),
+            });
+            // Open the run's root span on first sight; later events nest under it.
+            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 ? api_1.trace.setSpan(api_1.context.active(), root) : api_1.context.active();
+            // A step/signal/sleep event → give it its own child span so it's a distinct node in the
+            // trace; run-level events record directly on the root. Either way the active span at record
+            // time carries the run's traceId, so all entries group into one trace.
+            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);
+                api_1.context.with(api_1.trace.setSpan(base, step), record);
+                step.end();
+            }
+            else {
+                api_1.context.with(base, record);
+            }
+            // Close the run's root span when it leaves the running state.
+            if (event.type === 'run.completed' || event.type === 'run.suspended') {
+                root?.end();
+                this.roots.delete(event.runId);
+            }
+            else if (event.type === 'run.failed') {
+                root?.setStatus({ code: api_1.SpanStatusCode.ERROR, message: event.error?.message });
+                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;
+    }
+}
+exports.DurableTelescopeWatcher = DurableTelescopeWatcher;
+//# sourceMappingURL=durable-telescope.watcher.js.map

package/dist/durable-telescope.watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-telescope.watcher.js","sourceRoot":"","sources":["../src/durable-telescope.watcher.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './durable-telescope.watcher';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./durable-telescope.watcher"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8DAA4C"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@dudousxd/nestjs-durable-telescope",
+  "version": "0.1.0",
+  "description": "Telescope watcher for nestjs-durable — workflow runs and steps as Telescope entries",
+  "license": "MIT",
+  "author": "Davide Carvalho",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DavideCarvalho/nestjs-durable.git",
+    "directory": "packages/telescope"
+  },
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@dudousxd/nestjs-durable-core": ">=0.1.0 <1.0.0",
+    "@dudousxd/nestjs-telescope": ">=1.0.0 <2.0.0",
+    "@nestjs/core": "^10.0.0 || ^11.0.0",
+    "@opentelemetry/api": "^1.0.0"
+  },
+  "devDependencies": {
+    "@dudousxd/nestjs-telescope": "1.7.0",
+    "@nestjs/core": "11.1.26",
+    "@opentelemetry/api": "1.9.0",
+    "typescript": "5.9.3",
+    "@dudousxd/nestjs-durable-core": "^0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}