Distributed Tracing

W3C trace context propagation for observability.

Overview

Saga Bus automatically propagates W3C trace context through messages:

Press enter or space to select a node.You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Trace Context

Trace context is stored in saga metadata:

interface SagaStateMetadata {
  traceParent?: string | null;  // W3C traceparent header
  traceState?: string | null;   // W3C tracestate header
}

Automatic Propagation

When you publish messages, trace context flows automatically:

.on('OrderSubmitted')
  .handle(async (msg, state, ctx) => {
    // traceparent is automatically included
    await ctx.publish({
      type: 'CapturePayment',
      orderId: state.orderId,
    });

    return state;
  })

OpenTelemetry Integration

Use the tracing middleware for full OpenTelemetry support:

import { createTracingMiddleware } from '@saga-bus/middleware-tracing';

const bus = createBus({
  transport,
  store,
  sagas: [{ definition: orderSaga }],
  middleware: [
    createTracingMiddleware({
      serviceName: 'order-service',
    }),
  ],
});

This creates spans for:

• Message handling
• State persistence
• Outgoing publishes

Viewing Traces

With a tracing backend (Jaeger, Zipkin, etc.):

Press enter or space to select a node.You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Custom Attributes

Add custom span attributes:

.on('OrderSubmitted')
  .handle(async (msg, state, ctx) => {
    ctx.setMetadata('order.total', state.total);
    ctx.setMetadata('order.itemCount', state.items.length);
    return state;
  })

Learn More

• Tracing Middleware - Full configuration options
• Observability - Production setup