@kronos-ts/opentelemetry 0.1.4 → 0.2.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { createOpenTelemetrySpanFactory, type OpenTelemetrySpanFactoryOptions, } from "./opentelemetry-span-factory.js";
 export { openTelemetry } from "./opentelemetry.js";
+export { createOpenTelemetryDeadLetterListener } from "./opentelemetry-dead-letter-listener.js";
 export { createTracingCommandBus } from "@kronos-ts/messaging";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,EAC9B,KAAK,+BAA+B,GACrC,MAAM,iCAAiC,CAAA;AAExC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAGlD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,EAC9B,KAAK,+BAA+B,GACrC,MAAM,iCAAiC,CAAA;AAExC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,OAAO,EAAE,qCAAqC,EAAE,MAAM,yCAAyC,CAAA;AAG/F,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/index.js

@@ -1,5 +1,6 @@
 export { createOpenTelemetrySpanFactory, } from "./opentelemetry-span-factory.js";
 export { openTelemetry } from "./opentelemetry.js";
+export { createOpenTelemetryDeadLetterListener } from "./opentelemetry-dead-letter-listener.js";
 // Re-export tracing command bus for convenience
 export { createTracingCommandBus } from "@kronos-ts/messaging";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,GAE/B,MAAM,iCAAiC,CAAA;AAExC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,gDAAgD;AAChD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,GAE/B,MAAM,iCAAiC,CAAA;AAExC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,OAAO,EAAE,qCAAqC,EAAE,MAAM,yCAAyC,CAAA;AAE/F,gDAAgD;AAChD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/opentelemetry-dead-letter-listener.d.ts

@@ -0,0 +1,21 @@
+import type { DeadLetterListener, SpanFactory } from "@kronos-ts/messaging";
+import { type OpenTelemetrySpanFactoryOptions } from "./opentelemetry-span-factory.js";
+/**
+ * An OpenTelemetry {@link DeadLetterListener} that emits a short internal span
+ * for each dead-letter lifecycle transition, recording the cause as a span
+ * exception on failures and overflow (backpressure).
+ *
+ * Attach it to a processor via the builder:
+ * ```typescript
+ * trackingProcessor("balances")
+ *   .deadLetterQueue(dlq)
+ *   .deadLetterListener(createOpenTelemetryDeadLetterListener())
+ * ```
+ *
+ * Unlike {@link openTelemetry} (which decorates the command bus and enhances
+ * handlers app-wide), the DLQ listener is attached per processor, so this is a
+ * standalone factory. Pass a shared `spanFactory` to correlate with the rest of
+ * your tracing, or let it build one from `options`.
+ */
+export declare function createOpenTelemetryDeadLetterListener(options?: OpenTelemetrySpanFactoryOptions, spanFactory?: SpanFactory): DeadLetterListener;
+//# sourceMappingURL=opentelemetry-dead-letter-listener.d.ts.map

package/dist/opentelemetry-dead-letter-listener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opentelemetry-dead-letter-listener.d.ts","sourceRoot":"","sources":["../src/opentelemetry-dead-letter-listener.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAC3E,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,iCAAiC,CAAA;AAExC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qCAAqC,CACnD,OAAO,GAAE,+BAAoC,EAC7C,WAAW,GAAE,WAAqD,GACjE,kBAAkB,CA4BpB"}

package/dist/opentelemetry-dead-letter-listener.js

@@ -0,0 +1,52 @@
+import { createOpenTelemetrySpanFactory, } from "./opentelemetry-span-factory.js";
+/**
+ * An OpenTelemetry {@link DeadLetterListener} that emits a short internal span
+ * for each dead-letter lifecycle transition, recording the cause as a span
+ * exception on failures and overflow (backpressure).
+ *
+ * Attach it to a processor via the builder:
+ * ```typescript
+ * trackingProcessor("balances")
+ *   .deadLetterQueue(dlq)
+ *   .deadLetterListener(createOpenTelemetryDeadLetterListener())
+ * ```
+ *
+ * Unlike {@link openTelemetry} (which decorates the command bus and enhances
+ * handlers app-wide), the DLQ listener is attached per processor, so this is a
+ * standalone factory. Pass a shared `spanFactory` to correlate with the rest of
+ * your tracing, or let it build one from `options`.
+ */
+export function createOpenTelemetryDeadLetterListener(options = {}, spanFactory = createOpenTelemetrySpanFactory(options)) {
+    const emit = (name, error) => {
+        const span = spanFactory.createInternalSpan(name).start();
+        // recordException ends the span; otherwise end it normally.
+        if (error)
+            span.recordException(error);
+        else
+            span.end();
+    };
+    return {
+        onEnqueued(letter, info) {
+            if (info.blocked)
+                emit("dlq.blocked");
+            else
+                emit("dlq.enqueue", letter.cause);
+        },
+        onEvicted() {
+            emit("dlq.evict");
+        },
+        onRequeued() {
+            emit("dlq.requeue");
+        },
+        onReprocessSuccess() {
+            emit("dlq.reprocess.success");
+        },
+        onReprocessFailure(_letter, cause) {
+            emit("dlq.reprocess.failure", cause);
+        },
+        onOverflow(_sequenceIdentifier, cause) {
+            emit("dlq.overflow", cause);
+        },
+    };
+}
+//# sourceMappingURL=opentelemetry-dead-letter-listener.js.map

package/dist/opentelemetry-dead-letter-listener.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"opentelemetry-dead-letter-listener.js","sourceRoot":"","sources":["../src/opentelemetry-dead-letter-listener.ts"],"names":[],"mappings":"AACA,OAAO,EACL,8BAA8B,GAE/B,MAAM,iCAAiC,CAAA;AAExC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,qCAAqC,CACnD,UAA2C,EAAE,EAC7C,cAA2B,8BAA8B,CAAC,OAAO,CAAC;IAElE,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,KAAa,EAAE,EAAE;QAC3C,MAAM,IAAI,GAAG,WAAW,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,CAAA;QACzD,4DAA4D;QAC5D,IAAI,KAAK;YAAE,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,CAAA;;YACjC,IAAI,CAAC,GAAG,EAAE,CAAA;IACjB,CAAC,CAAA;IACD,OAAO;QACL,UAAU,CAAC,MAAM,EAAE,IAAI;YACrB,IAAI,IAAI,CAAC,OAAO;gBAAE,IAAI,CAAC,aAAa,CAAC,CAAA;;gBAChC,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;QACxC,CAAC;QACD,SAAS;YACP,IAAI,CAAC,WAAW,CAAC,CAAA;QACnB,CAAC;QACD,UAAU;YACR,IAAI,CAAC,aAAa,CAAC,CAAA;QACrB,CAAC;QACD,kBAAkB;YAChB,IAAI,CAAC,uBAAuB,CAAC,CAAA;QAC/B,CAAC;QACD,kBAAkB,CAAC,OAAO,EAAE,KAAK;YAC/B,IAAI,CAAC,uBAAuB,EAAE,KAAK,CAAC,CAAA;QACtC,CAAC;QACD,UAAU,CAAC,mBAAmB,EAAE,KAAK;YACnC,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,CAAA;QAC7B,CAAC;KACF,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kronos-ts/opentelemetry",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "OpenTelemetry extension for Kronos — tracing for commands and events.",
   "license": "Apache-2.0",
   "type": "module",
@@ -49,14 +49,14 @@
     }
   },
   "dependencies": {
-    "@kronos-ts/common": "0.1.0",
-    "@kronos-ts/app": "0.1.0",
-    "@kronos-ts/messaging": "0.1.0",
+    "@kronos-ts/common": "0.1.1",
+    "@kronos-ts/app": "0.3.2",
+    "@kronos-ts/messaging": "0.4.0",
     "@opentelemetry/api": "^1.9"
   },
   "devDependencies": {
-    "@kronos-ts/eventsourcing": "0.1.0",
-    "@kronos-ts/modelling": "0.1.0",
+    "@kronos-ts/eventsourcing": "0.1.5",
+    "@kronos-ts/modelling": "0.2.2",
     "@opentelemetry/sdk-trace-base": "^1.30.0",
     "@opentelemetry/sdk-trace-node": "^1.30.0",
     "zod": "^4.3.6"

package/src/index.ts

@@ -5,5 +5,7 @@ export {
 
 export { openTelemetry } from "./opentelemetry.js"
 
+export { createOpenTelemetryDeadLetterListener } from "./opentelemetry-dead-letter-listener.js"
+
 // Re-export tracing command bus for convenience
 export { createTracingCommandBus } from "@kronos-ts/messaging"

package/src/opentelemetry-dead-letter-listener.ts

@@ -0,0 +1,55 @@
+import type { DeadLetterListener, SpanFactory } from "@kronos-ts/messaging"
+import {
+  createOpenTelemetrySpanFactory,
+  type OpenTelemetrySpanFactoryOptions,
+} from "./opentelemetry-span-factory.js"
+
+/**
+ * An OpenTelemetry {@link DeadLetterListener} that emits a short internal span
+ * for each dead-letter lifecycle transition, recording the cause as a span
+ * exception on failures and overflow (backpressure).
+ *
+ * Attach it to a processor via the builder:
+ * ```typescript
+ * trackingProcessor("balances")
+ *   .deadLetterQueue(dlq)
+ *   .deadLetterListener(createOpenTelemetryDeadLetterListener())
+ * ```
+ *
+ * Unlike {@link openTelemetry} (which decorates the command bus and enhances
+ * handlers app-wide), the DLQ listener is attached per processor, so this is a
+ * standalone factory. Pass a shared `spanFactory` to correlate with the rest of
+ * your tracing, or let it build one from `options`.
+ */
+export function createOpenTelemetryDeadLetterListener(
+  options: OpenTelemetrySpanFactoryOptions = {},
+  spanFactory: SpanFactory = createOpenTelemetrySpanFactory(options),
+): DeadLetterListener {
+  const emit = (name: string, error?: Error) => {
+    const span = spanFactory.createInternalSpan(name).start()
+    // recordException ends the span; otherwise end it normally.
+    if (error) span.recordException(error)
+    else span.end()
+  }
+  return {
+    onEnqueued(letter, info) {
+      if (info.blocked) emit("dlq.blocked")
+      else emit("dlq.enqueue", letter.cause)
+    },
+    onEvicted() {
+      emit("dlq.evict")
+    },
+    onRequeued() {
+      emit("dlq.requeue")
+    },
+    onReprocessSuccess() {
+      emit("dlq.reprocess.success")
+    },
+    onReprocessFailure(_letter, cause) {
+      emit("dlq.reprocess.failure", cause)
+    },
+    onOverflow(_sequenceIdentifier, cause) {
+      emit("dlq.overflow", cause)
+    },
+  }
+}