@saga-bus/middleware-tracing 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Dean Foran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @saga-bus/middleware-tracing
+
+OpenTelemetry distributed tracing middleware for saga-bus.
+
+## Installation
+
+```bash
+pnpm add @saga-bus/middleware-tracing @opentelemetry/api
+```
+
+## Usage
+
+```typescript
+import { createTracingMiddleware } from "@saga-bus/middleware-tracing";
+import { createBus } from "@saga-bus/core";
+import { trace } from "@opentelemetry/api";
+
+const tracingMiddleware = createTracingMiddleware({
+  tracer: trace.getTracer("my-service"),
+});
+
+const bus = createBus({
+  middleware: [tracingMiddleware],
+  sagas: [...],
+  transport,
+});
+```
+
+## Features
+
+- Automatic span creation for message processing
+- W3C Trace Context propagation (traceparent/tracestate headers)
+- Span attributes for message type, saga ID, correlation ID
+- Error recording on handler failures
+- Optional payload recording
+
+## Trace Context Propagation
+
+The middleware automatically propagates trace context across service boundaries:
+
+```typescript
+import { createPublishTracer } from "@saga-bus/middleware-tracing";
+
+const publishWithTracing = createPublishTracer(bus, {
+  tracer: trace.getTracer("my-service"),
+});
+
+// Automatically injects traceparent/tracestate headers
+await publishWithTracing({
+  type: "OrderCreated",
+  payload: { orderId: "123" },
+});
+```
+
+## Span Attributes
+
+Each message processing span includes:
+
+| Attribute | Description |
+|-----------|-------------|
+| `messaging.system` | `"saga-bus"` |
+| `messaging.operation` | `"process"` |
+| `messaging.message.type` | Message type |
+| `saga.name` | Saga name |
+| `saga.id` | Saga instance ID |
+| `messaging.message.correlation_id` | Correlation ID |
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `tracer` | `Tracer` | global | OpenTelemetry tracer |
+| `tracerName` | `string` | `"@saga-bus/middleware-tracing"` | Tracer name |
+| `recordPayload` | `boolean` | `false` | Record payload as attribute |
+| `maxPayloadSize` | `number` | `1024` | Max payload size to record |
+| `attributeExtractor` | `function` | - | Custom attribute extractor |
+
+## Custom Attributes
+
+```typescript
+createTracingMiddleware({
+  attributeExtractor: (envelope) => ({
+    "custom.order_id": envelope.payload?.orderId,
+    "custom.priority": envelope.payload?.priority,
+  }),
+});
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,153 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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, {
+  createPublishTracer: () => createPublishTracer,
+  createTracingMiddleware: () => createTracingMiddleware
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/TracingMiddleware.ts
+var import_api = require("@opentelemetry/api");
+var TRACER_NAME = "@saga-bus/middleware-tracing";
+function createTracingMiddleware(options = {}) {
+  const tracer = options.tracer ?? import_api.trace.getTracer(options.tracerName ?? TRACER_NAME);
+  const recordPayload = options.recordPayload ?? false;
+  const maxPayloadSize = options.maxPayloadSize ?? 1024;
+  const attributeExtractor = options.attributeExtractor;
+  return async (ctx, next) => {
+    const { envelope } = ctx;
+    let parentContext = import_api.context.active();
+    const existingState = ctx.existingState;
+    if (existingState?.metadata?.traceParent) {
+      const carrier = {
+        traceparent: existingState.metadata.traceParent,
+        tracestate: existingState.metadata.traceState ?? void 0
+      };
+      parentContext = import_api.propagation.extract(import_api.context.active(), carrier);
+    } else if (envelope.headers?.traceparent) {
+      parentContext = extractContext(envelope);
+    }
+    const spanName = `saga-bus.handle ${envelope.type}`;
+    const span = tracer.startSpan(
+      spanName,
+      {
+        kind: import_api.SpanKind.CONSUMER,
+        attributes: buildAttributes(envelope, recordPayload, maxPayloadSize)
+      },
+      parentContext
+    );
+    if (attributeExtractor) {
+      try {
+        const customAttrs = attributeExtractor(envelope);
+        span.setAttributes(customAttrs);
+      } catch {
+      }
+    }
+    span.setAttribute("saga.name", ctx.sagaName);
+    if (ctx.sagaId) {
+      span.setAttribute("saga.id", ctx.sagaId);
+    }
+    span.setAttribute("saga.correlation_id", ctx.correlationId);
+    span.setAttribute("saga.is_new", !existingState);
+    if (!existingState || !existingState.metadata?.traceParent) {
+      const carrier = {};
+      import_api.propagation.inject(import_api.trace.setSpan(import_api.context.active(), span), carrier);
+      if (carrier.traceparent) {
+        ctx.setTraceContext(carrier.traceparent, carrier.tracestate ?? null);
+      }
+    }
+    try {
+      await import_api.context.with(import_api.trace.setSpan(import_api.context.active(), span), async () => {
+        await next();
+      });
+      span.setStatus({ code: import_api.SpanStatusCode.OK });
+    } catch (error) {
+      span.setStatus({
+        code: import_api.SpanStatusCode.ERROR,
+        message: error instanceof Error ? error.message : String(error)
+      });
+      span.recordException(error);
+      throw error;
+    } finally {
+      span.end();
+    }
+  };
+}
+function createPublishTracer(options = {}) {
+  const tracer = options.tracer ?? import_api.trace.getTracer(options.tracerName ?? TRACER_NAME);
+  return (envelope) => {
+    const span = tracer.startSpan(`saga-bus.publish ${envelope.type}`, {
+      kind: import_api.SpanKind.PRODUCER,
+      attributes: {
+        "messaging.system": "saga-bus",
+        "messaging.operation": "publish",
+        "messaging.message.id": envelope.id,
+        "messaging.message.type": envelope.type
+      }
+    });
+    const traceHeaders = {};
+    import_api.propagation.inject(import_api.trace.setSpan(import_api.context.active(), span), traceHeaders);
+    span.end();
+    return {
+      ...envelope,
+      headers: {
+        ...envelope.headers,
+        ...traceHeaders.traceparent && { traceparent: traceHeaders.traceparent },
+        ...traceHeaders.tracestate && { tracestate: traceHeaders.tracestate }
+      }
+    };
+  };
+}
+function extractContext(envelope) {
+  const headers = envelope.headers;
+  if (!headers.traceparent) {
+    return import_api.context.active();
+  }
+  return import_api.propagation.extract(import_api.context.active(), headers);
+}
+function buildAttributes(envelope, recordPayload, maxPayloadSize) {
+  const attrs = {
+    "messaging.system": "saga-bus",
+    "messaging.operation": "process",
+    "messaging.message.id": envelope.id,
+    "messaging.message.type": envelope.type
+  };
+  if (envelope.partitionKey) {
+    attrs["messaging.message.partition_key"] = envelope.partitionKey;
+  }
+  if (recordPayload && envelope.payload !== void 0) {
+    const payloadStr = JSON.stringify(envelope.payload);
+    if (payloadStr.length <= maxPayloadSize) {
+      attrs["messaging.message.payload"] = payloadStr;
+    } else {
+      attrs["messaging.message.payload"] = payloadStr.slice(0, maxPayloadSize) + "...";
+      attrs["messaging.message.payload_truncated"] = true;
+    }
+  }
+  return attrs;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createPublishTracer,
+  createTracingMiddleware
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/TracingMiddleware.ts"],"sourcesContent":["export {\n  createTracingMiddleware,\n  createPublishTracer,\n} from \"./TracingMiddleware.js\";\nexport type {\n  TracingMiddlewareOptions,\n  TraceContextHeaders,\n} from \"./types.js\";\n","import {\n  trace,\n  context,\n  SpanKind,\n  SpanStatusCode,\n  propagation,\n  type Context,\n  type Attributes,\n} from \"@opentelemetry/api\";\nimport type {\n  SagaMiddleware,\n  SagaPipelineContext,\n  MessageEnvelope,\n} from \"@saga-bus/core\";\nimport type { TracingMiddlewareOptions, TraceContextHeaders } from \"./types.js\";\n\nconst TRACER_NAME = \"@saga-bus/middleware-tracing\";\n\n/**\n * OpenTelemetry tracing middleware for saga-bus.\n *\n * Creates spans for message handling with proper context propagation\n * for distributed tracing across services. Supports saga-correlated tracing\n * where all messages for the same saga instance share the same trace.\n *\n * @example\n * ```typescript\n * import { trace } from \"@opentelemetry/api\";\n * import { createTracingMiddleware } from \"@saga-bus/middleware-tracing\";\n *\n * const middleware = createTracingMiddleware({\n *   tracer: trace.getTracer(\"my-service\"),\n * });\n *\n * const bus = createMessageBus({\n *   middleware: [middleware],\n * });\n * ```\n */\nexport function createTracingMiddleware(\n  options: TracingMiddlewareOptions = {}\n): SagaMiddleware {\n  const tracer =\n    options.tracer ?? trace.getTracer(options.tracerName ?? TRACER_NAME);\n  const recordPayload = options.recordPayload ?? false;\n  const maxPayloadSize = options.maxPayloadSize ?? 1024;\n  const attributeExtractor = options.attributeExtractor;\n\n  return async (ctx: SagaPipelineContext, next: () => Promise<void>) => {\n    const { envelope } = ctx;\n\n    // Determine parent context:\n    // 1. First check if saga state has stored trace context (for saga correlation)\n    // 2. Fall back to message headers (for standard distributed tracing)\n    // 3. Fall back to active context\n    let parentContext = context.active();\n\n    // Check existing saga state for stored trace context\n    const existingState = ctx.existingState;\n    if (existingState?.metadata?.traceParent) {\n      // Use saga's stored trace context for correlation\n      const carrier: TraceContextHeaders = {\n        traceparent: existingState.metadata.traceParent,\n        tracestate: existingState.metadata.traceState ?? undefined,\n      };\n      parentContext = propagation.extract(context.active(), carrier);\n    } else if (envelope.headers?.traceparent) {\n      // Use message header trace context\n      parentContext = extractContext(envelope);\n    }\n\n    // Start span with parent context\n    const spanName = `saga-bus.handle ${envelope.type}`;\n    const span = tracer.startSpan(\n      spanName,\n      {\n        kind: SpanKind.CONSUMER,\n        attributes: buildAttributes(envelope, recordPayload, maxPayloadSize),\n      },\n      parentContext\n    );\n\n    // Add custom attributes\n    if (attributeExtractor) {\n      try {\n        const customAttrs = attributeExtractor(envelope);\n        span.setAttributes(customAttrs);\n      } catch {\n        // Ignore extractor errors\n      }\n    }\n\n    // Add saga attributes\n    span.setAttribute(\"saga.name\", ctx.sagaName);\n    if (ctx.sagaId) {\n      span.setAttribute(\"saga.id\", ctx.sagaId);\n    }\n    span.setAttribute(\"saga.correlation_id\", ctx.correlationId);\n    span.setAttribute(\"saga.is_new\", !existingState);\n\n    // If this is a new saga or saga has no trace context, store the current trace context\n    // so subsequent messages can be correlated\n    if (!existingState || !existingState.metadata?.traceParent) {\n      const carrier: TraceContextHeaders = {};\n      propagation.inject(trace.setSpan(context.active(), span), carrier);\n      if (carrier.traceparent) {\n        // Store trace context in pipeline context for orchestrator to persist\n        ctx.setTraceContext(carrier.traceparent, carrier.tracestate ?? null);\n      }\n    }\n\n    try {\n      // Run next middleware within span context\n      await context.with(trace.setSpan(context.active(), span), async () => {\n        await next();\n      });\n\n      span.setStatus({ code: SpanStatusCode.OK });\n    } catch (error) {\n      span.setStatus({\n        code: SpanStatusCode.ERROR,\n        message: error instanceof Error ? error.message : String(error),\n      });\n      span.recordException(error as Error);\n      throw error;\n    } finally {\n      span.end();\n    }\n  };\n}\n\n/**\n * Create a publish interceptor that adds tracing to outbound messages.\n *\n * @example\n * ```typescript\n * const tracer = createPublishTracer({\n *   tracer: trace.getTracer(\"my-service\"),\n * });\n *\n * // Before publishing, wrap the envelope\n * const tracedEnvelope = tracer(envelope);\n * await transport.publish(tracedEnvelope.payload, options);\n * ```\n */\nexport function createPublishTracer(\n  options: TracingMiddlewareOptions = {}\n): (envelope: MessageEnvelope) => MessageEnvelope {\n  const tracer =\n    options.tracer ?? trace.getTracer(options.tracerName ?? TRACER_NAME);\n\n  return (envelope: MessageEnvelope): MessageEnvelope => {\n    const span = tracer.startSpan(`saga-bus.publish ${envelope.type}`, {\n      kind: SpanKind.PRODUCER,\n      attributes: {\n        \"messaging.system\": \"saga-bus\",\n        \"messaging.operation\": \"publish\",\n        \"messaging.message.id\": envelope.id,\n        \"messaging.message.type\": envelope.type,\n      },\n    });\n\n    // Inject trace context into message headers\n    const traceHeaders: TraceContextHeaders = {};\n    propagation.inject(trace.setSpan(context.active(), span), traceHeaders);\n\n    span.end();\n\n    // Return envelope with trace headers merged into existing headers\n    return {\n      ...envelope,\n      headers: {\n        ...envelope.headers,\n        ...(traceHeaders.traceparent && { traceparent: traceHeaders.traceparent }),\n        ...(traceHeaders.tracestate && { tracestate: traceHeaders.tracestate }),\n      },\n    };\n  };\n}\n\n/**\n * Extract trace context from message headers.\n */\nfunction extractContext(envelope: MessageEnvelope): Context {\n  const headers = envelope.headers;\n\n  if (!headers.traceparent) {\n    return context.active();\n  }\n\n  return propagation.extract(context.active(), headers);\n}\n\n/**\n * Build standard span attributes from message envelope.\n */\nfunction buildAttributes(\n  envelope: MessageEnvelope,\n  recordPayload: boolean,\n  maxPayloadSize: number\n): Attributes {\n  const attrs: Attributes = {\n    \"messaging.system\": \"saga-bus\",\n    \"messaging.operation\": \"process\",\n    \"messaging.message.id\": envelope.id,\n    \"messaging.message.type\": envelope.type,\n  };\n\n  if (envelope.partitionKey) {\n    attrs[\"messaging.message.partition_key\"] = envelope.partitionKey;\n  }\n\n  if (recordPayload && envelope.payload !== undefined) {\n    const payloadStr = JSON.stringify(envelope.payload);\n    if (payloadStr.length <= maxPayloadSize) {\n      attrs[\"messaging.message.payload\"] = payloadStr;\n    } else {\n      attrs[\"messaging.message.payload\"] =\n        payloadStr.slice(0, maxPayloadSize) + \"...\";\n      attrs[\"messaging.message.payload_truncated\"] = true;\n    }\n  }\n\n  return attrs;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,81 @@
+import { MessageEnvelope, SagaMiddleware } from '@saga-bus/core';
+import { Tracer, Attributes } from '@opentelemetry/api';
+
+/**
+ * Tracing middleware configuration options.
+ */
+interface TracingMiddlewareOptions {
+    /**
+     * OpenTelemetry tracer instance.
+     * If not provided, uses the global tracer.
+     */
+    tracer?: Tracer;
+    /**
+     * Tracer name when creating from global provider.
+     * @default "@saga-bus/middleware-tracing"
+     */
+    tracerName?: string;
+    /**
+     * Whether to record message payloads as span attributes.
+     * May expose sensitive data - use with caution.
+     * @default false
+     */
+    recordPayload?: boolean;
+    /**
+     * Maximum payload size to record (bytes).
+     * @default 1024
+     */
+    maxPayloadSize?: number;
+    /**
+     * Custom attribute extractor.
+     * Called for each message to add custom attributes.
+     */
+    attributeExtractor?: (envelope: MessageEnvelope) => Attributes;
+}
+/**
+ * Trace context propagation headers.
+ */
+interface TraceContextHeaders {
+    traceparent?: string;
+    tracestate?: string;
+}
+
+/**
+ * OpenTelemetry tracing middleware for saga-bus.
+ *
+ * Creates spans for message handling with proper context propagation
+ * for distributed tracing across services. Supports saga-correlated tracing
+ * where all messages for the same saga instance share the same trace.
+ *
+ * @example
+ * ```typescript
+ * import { trace } from "@opentelemetry/api";
+ * import { createTracingMiddleware } from "@saga-bus/middleware-tracing";
+ *
+ * const middleware = createTracingMiddleware({
+ *   tracer: trace.getTracer("my-service"),
+ * });
+ *
+ * const bus = createMessageBus({
+ *   middleware: [middleware],
+ * });
+ * ```
+ */
+declare function createTracingMiddleware(options?: TracingMiddlewareOptions): SagaMiddleware;
+/**
+ * Create a publish interceptor that adds tracing to outbound messages.
+ *
+ * @example
+ * ```typescript
+ * const tracer = createPublishTracer({
+ *   tracer: trace.getTracer("my-service"),
+ * });
+ *
+ * // Before publishing, wrap the envelope
+ * const tracedEnvelope = tracer(envelope);
+ * await transport.publish(tracedEnvelope.payload, options);
+ * ```
+ */
+declare function createPublishTracer(options?: TracingMiddlewareOptions): (envelope: MessageEnvelope) => MessageEnvelope;
+
+export { type TraceContextHeaders, type TracingMiddlewareOptions, createPublishTracer, createTracingMiddleware };

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+import { MessageEnvelope, SagaMiddleware } from '@saga-bus/core';
+import { Tracer, Attributes } from '@opentelemetry/api';
+
+/**
+ * Tracing middleware configuration options.
+ */
+interface TracingMiddlewareOptions {
+    /**
+     * OpenTelemetry tracer instance.
+     * If not provided, uses the global tracer.
+     */
+    tracer?: Tracer;
+    /**
+     * Tracer name when creating from global provider.
+     * @default "@saga-bus/middleware-tracing"
+     */
+    tracerName?: string;
+    /**
+     * Whether to record message payloads as span attributes.
+     * May expose sensitive data - use with caution.
+     * @default false
+     */
+    recordPayload?: boolean;
+    /**
+     * Maximum payload size to record (bytes).
+     * @default 1024
+     */
+    maxPayloadSize?: number;
+    /**
+     * Custom attribute extractor.
+     * Called for each message to add custom attributes.
+     */
+    attributeExtractor?: (envelope: MessageEnvelope) => Attributes;
+}
+/**
+ * Trace context propagation headers.
+ */
+interface TraceContextHeaders {
+    traceparent?: string;
+    tracestate?: string;
+}
+
+/**
+ * OpenTelemetry tracing middleware for saga-bus.
+ *
+ * Creates spans for message handling with proper context propagation
+ * for distributed tracing across services. Supports saga-correlated tracing
+ * where all messages for the same saga instance share the same trace.
+ *
+ * @example
+ * ```typescript
+ * import { trace } from "@opentelemetry/api";
+ * import { createTracingMiddleware } from "@saga-bus/middleware-tracing";
+ *
+ * const middleware = createTracingMiddleware({
+ *   tracer: trace.getTracer("my-service"),
+ * });
+ *
+ * const bus = createMessageBus({
+ *   middleware: [middleware],
+ * });
+ * ```
+ */
+declare function createTracingMiddleware(options?: TracingMiddlewareOptions): SagaMiddleware;
+/**
+ * Create a publish interceptor that adds tracing to outbound messages.
+ *
+ * @example
+ * ```typescript
+ * const tracer = createPublishTracer({
+ *   tracer: trace.getTracer("my-service"),
+ * });
+ *
+ * // Before publishing, wrap the envelope
+ * const tracedEnvelope = tracer(envelope);
+ * await transport.publish(tracedEnvelope.payload, options);
+ * ```
+ */
+declare function createPublishTracer(options?: TracingMiddlewareOptions): (envelope: MessageEnvelope) => MessageEnvelope;
+
+export { type TraceContextHeaders, type TracingMiddlewareOptions, createPublishTracer, createTracingMiddleware };

package/dist/index.js

@@ -0,0 +1,131 @@
+// src/TracingMiddleware.ts
+import {
+  trace,
+  context,
+  SpanKind,
+  SpanStatusCode,
+  propagation
+} from "@opentelemetry/api";
+var TRACER_NAME = "@saga-bus/middleware-tracing";
+function createTracingMiddleware(options = {}) {
+  const tracer = options.tracer ?? trace.getTracer(options.tracerName ?? TRACER_NAME);
+  const recordPayload = options.recordPayload ?? false;
+  const maxPayloadSize = options.maxPayloadSize ?? 1024;
+  const attributeExtractor = options.attributeExtractor;
+  return async (ctx, next) => {
+    const { envelope } = ctx;
+    let parentContext = context.active();
+    const existingState = ctx.existingState;
+    if (existingState?.metadata?.traceParent) {
+      const carrier = {
+        traceparent: existingState.metadata.traceParent,
+        tracestate: existingState.metadata.traceState ?? void 0
+      };
+      parentContext = propagation.extract(context.active(), carrier);
+    } else if (envelope.headers?.traceparent) {
+      parentContext = extractContext(envelope);
+    }
+    const spanName = `saga-bus.handle ${envelope.type}`;
+    const span = tracer.startSpan(
+      spanName,
+      {
+        kind: SpanKind.CONSUMER,
+        attributes: buildAttributes(envelope, recordPayload, maxPayloadSize)
+      },
+      parentContext
+    );
+    if (attributeExtractor) {
+      try {
+        const customAttrs = attributeExtractor(envelope);
+        span.setAttributes(customAttrs);
+      } catch {
+      }
+    }
+    span.setAttribute("saga.name", ctx.sagaName);
+    if (ctx.sagaId) {
+      span.setAttribute("saga.id", ctx.sagaId);
+    }
+    span.setAttribute("saga.correlation_id", ctx.correlationId);
+    span.setAttribute("saga.is_new", !existingState);
+    if (!existingState || !existingState.metadata?.traceParent) {
+      const carrier = {};
+      propagation.inject(trace.setSpan(context.active(), span), carrier);
+      if (carrier.traceparent) {
+        ctx.setTraceContext(carrier.traceparent, carrier.tracestate ?? null);
+      }
+    }
+    try {
+      await context.with(trace.setSpan(context.active(), span), async () => {
+        await next();
+      });
+      span.setStatus({ code: SpanStatusCode.OK });
+    } catch (error) {
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error instanceof Error ? error.message : String(error)
+      });
+      span.recordException(error);
+      throw error;
+    } finally {
+      span.end();
+    }
+  };
+}
+function createPublishTracer(options = {}) {
+  const tracer = options.tracer ?? trace.getTracer(options.tracerName ?? TRACER_NAME);
+  return (envelope) => {
+    const span = tracer.startSpan(`saga-bus.publish ${envelope.type}`, {
+      kind: SpanKind.PRODUCER,
+      attributes: {
+        "messaging.system": "saga-bus",
+        "messaging.operation": "publish",
+        "messaging.message.id": envelope.id,
+        "messaging.message.type": envelope.type
+      }
+    });
+    const traceHeaders = {};
+    propagation.inject(trace.setSpan(context.active(), span), traceHeaders);
+    span.end();
+    return {
+      ...envelope,
+      headers: {
+        ...envelope.headers,
+        ...traceHeaders.traceparent && { traceparent: traceHeaders.traceparent },
+        ...traceHeaders.tracestate && { tracestate: traceHeaders.tracestate }
+      }
+    };
+  };
+}
+function extractContext(envelope) {
+  const headers = envelope.headers;
+  if (!headers.traceparent) {
+    return context.active();
+  }
+  return propagation.extract(context.active(), headers);
+}
+function buildAttributes(envelope, recordPayload, maxPayloadSize) {
+  const attrs = {
+    "messaging.system": "saga-bus",
+    "messaging.operation": "process",
+    "messaging.message.id": envelope.id,
+    "messaging.message.type": envelope.type
+  };
+  if (envelope.partitionKey) {
+    attrs["messaging.message.partition_key"] = envelope.partitionKey;
+  }
+  if (recordPayload && envelope.payload !== void 0) {
+    const payloadStr = JSON.stringify(envelope.payload);
+    if (payloadStr.length <= maxPayloadSize) {
+      attrs["messaging.message.payload"] = payloadStr;
+    } else {
+      attrs["messaging.message.payload"] = payloadStr.slice(0, maxPayloadSize) + "...";
+      attrs["messaging.message.payload_truncated"] = true;
+    }
+  }
+  return attrs;
+}
+export {
+  createPublishTracer,
+  createTracingMiddleware
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/TracingMiddleware.ts"],"sourcesContent":["import {\n  trace,\n  context,\n  SpanKind,\n  SpanStatusCode,\n  propagation,\n  type Context,\n  type Attributes,\n} from \"@opentelemetry/api\";\nimport type {\n  SagaMiddleware,\n  SagaPipelineContext,\n  MessageEnvelope,\n} from \"@saga-bus/core\";\nimport type { TracingMiddlewareOptions, TraceContextHeaders } from \"./types.js\";\n\nconst TRACER_NAME = \"@saga-bus/middleware-tracing\";\n\n/**\n * OpenTelemetry tracing middleware for saga-bus.\n *\n * Creates spans for message handling with proper context propagation\n * for distributed tracing across services. Supports saga-correlated tracing\n * where all messages for the same saga instance share the same trace.\n *\n * @example\n * ```typescript\n * import { trace } from \"@opentelemetry/api\";\n * import { createTracingMiddleware } from \"@saga-bus/middleware-tracing\";\n *\n * const middleware = createTracingMiddleware({\n *   tracer: trace.getTracer(\"my-service\"),\n * });\n *\n * const bus = createMessageBus({\n *   middleware: [middleware],\n * });\n * ```\n */\nexport function createTracingMiddleware(\n  options: TracingMiddlewareOptions = {}\n): SagaMiddleware {\n  const tracer =\n    options.tracer ?? trace.getTracer(options.tracerName ?? TRACER_NAME);\n  const recordPayload = options.recordPayload ?? false;\n  const maxPayloadSize = options.maxPayloadSize ?? 1024;\n  const attributeExtractor = options.attributeExtractor;\n\n  return async (ctx: SagaPipelineContext, next: () => Promise<void>) => {\n    const { envelope } = ctx;\n\n    // Determine parent context:\n    // 1. First check if saga state has stored trace context (for saga correlation)\n    // 2. Fall back to message headers (for standard distributed tracing)\n    // 3. Fall back to active context\n    let parentContext = context.active();\n\n    // Check existing saga state for stored trace context\n    const existingState = ctx.existingState;\n    if (existingState?.metadata?.traceParent) {\n      // Use saga's stored trace context for correlation\n      const carrier: TraceContextHeaders = {\n        traceparent: existingState.metadata.traceParent,\n        tracestate: existingState.metadata.traceState ?? undefined,\n      };\n      parentContext = propagation.extract(context.active(), carrier);\n    } else if (envelope.headers?.traceparent) {\n      // Use message header trace context\n      parentContext = extractContext(envelope);\n    }\n\n    // Start span with parent context\n    const spanName = `saga-bus.handle ${envelope.type}`;\n    const span = tracer.startSpan(\n      spanName,\n      {\n        kind: SpanKind.CONSUMER,\n        attributes: buildAttributes(envelope, recordPayload, maxPayloadSize),\n      },\n      parentContext\n    );\n\n    // Add custom attributes\n    if (attributeExtractor) {\n      try {\n        const customAttrs = attributeExtractor(envelope);\n        span.setAttributes(customAttrs);\n      } catch {\n        // Ignore extractor errors\n      }\n    }\n\n    // Add saga attributes\n    span.setAttribute(\"saga.name\", ctx.sagaName);\n    if (ctx.sagaId) {\n      span.setAttribute(\"saga.id\", ctx.sagaId);\n    }\n    span.setAttribute(\"saga.correlation_id\", ctx.correlationId);\n    span.setAttribute(\"saga.is_new\", !existingState);\n\n    // If this is a new saga or saga has no trace context, store the current trace context\n    // so subsequent messages can be correlated\n    if (!existingState || !existingState.metadata?.traceParent) {\n      const carrier: TraceContextHeaders = {};\n      propagation.inject(trace.setSpan(context.active(), span), carrier);\n      if (carrier.traceparent) {\n        // Store trace context in pipeline context for orchestrator to persist\n        ctx.setTraceContext(carrier.traceparent, carrier.tracestate ?? null);\n      }\n    }\n\n    try {\n      // Run next middleware within span context\n      await context.with(trace.setSpan(context.active(), span), async () => {\n        await next();\n      });\n\n      span.setStatus({ code: SpanStatusCode.OK });\n    } catch (error) {\n      span.setStatus({\n        code: SpanStatusCode.ERROR,\n        message: error instanceof Error ? error.message : String(error),\n      });\n      span.recordException(error as Error);\n      throw error;\n    } finally {\n      span.end();\n    }\n  };\n}\n\n/**\n * Create a publish interceptor that adds tracing to outbound messages.\n *\n * @example\n * ```typescript\n * const tracer = createPublishTracer({\n *   tracer: trace.getTracer(\"my-service\"),\n * });\n *\n * // Before publishing, wrap the envelope\n * const tracedEnvelope = tracer(envelope);\n * await transport.publish(tracedEnvelope.payload, options);\n * ```\n */\nexport function createPublishTracer(\n  options: TracingMiddlewareOptions = {}\n): (envelope: MessageEnvelope) => MessageEnvelope {\n  const tracer =\n    options.tracer ?? trace.getTracer(options.tracerName ?? TRACER_NAME);\n\n  return (envelope: MessageEnvelope): MessageEnvelope => {\n    const span = tracer.startSpan(`saga-bus.publish ${envelope.type}`, {\n      kind: SpanKind.PRODUCER,\n      attributes: {\n        \"messaging.system\": \"saga-bus\",\n        \"messaging.operation\": \"publish\",\n        \"messaging.message.id\": envelope.id,\n        \"messaging.message.type\": envelope.type,\n      },\n    });\n\n    // Inject trace context into message headers\n    const traceHeaders: TraceContextHeaders = {};\n    propagation.inject(trace.setSpan(context.active(), span), traceHeaders);\n\n    span.end();\n\n    // Return envelope with trace headers merged into existing headers\n    return {\n      ...envelope,\n      headers: {\n        ...envelope.headers,\n        ...(traceHeaders.traceparent && { traceparent: traceHeaders.traceparent }),\n        ...(traceHeaders.tracestate && { tracestate: traceHeaders.tracestate }),\n      },\n    };\n  };\n}\n\n/**\n * Extract trace context from message headers.\n */\nfunction extractContext(envelope: MessageEnvelope): Context {\n  const headers = envelope.headers;\n\n  if (!headers.traceparent) {\n    return context.active();\n  }\n\n  return propagation.extract(context.active(), headers);\n}\n\n/**\n * Build standard span attributes from message envelope.\n */\nfunction buildAttributes(\n  envelope: MessageEnvelope,\n  recordPayload: boolean,\n  maxPayloadSize: number\n): Attributes {\n  const attrs: Attributes = {\n    \"messaging.system\": \"saga-bus\",\n    \"messaging.operation\": \"process\",\n    \"messaging.message.id\": envelope.id,\n    \"messaging.message.type\": envelope.type,\n  };\n\n  if (envelope.partitionKey) {\n    attrs[\"messaging.message.partition_key\"] = envelope.partitionKey;\n  }\n\n  if (recordPayload && envelope.payload !== undefined) {\n    const payloadStr = JSON.stringify(envelope.payload);\n    if (payloadStr.length <= maxPayloadSize) {\n      attrs[\"messaging.message.payload\"] = payloadStr;\n    } else {\n      attrs[\"messaging.message.payload\"] =\n        payloadStr.slice(0, maxPayloadSize) + \"...\";\n      attrs[\"messaging.message.payload_truncated\"] = true;\n    }\n  }\n\n  return attrs;\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@saga-bus/middleware-tracing",
+  "version": "0.1.0",
+  "description": "OpenTelemetry tracing middleware for saga-bus",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deanforan/saga-bus.git",
+    "directory": "packages/middleware-tracing"
+  },
+  "keywords": [
+    "saga",
+    "message-bus",
+    "middleware",
+    "tracing",
+    "opentelemetry",
+    "otel"
+  ],
+  "dependencies": {
+    "@saga-bus/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-trace-base": "^1.25.0",
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.0.0",
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": ">=1.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}