Headers & Tracing

Rabbit Relay provides small helpers for adding metadata, headers, correlation IDs, and causation IDs to events.

These helpers keep event code clean and avoid repetitive manual meta mutation.

Why metadata matters

In event-driven systems, a single business action often creates multiple events.

Example:

order.created
  -> payment.requested
  -> payment.processed
  -> shipping.started

To debug this flow, events should share a correlation ID.

Each child event should also point to the event that caused it.

Event metadata

Rabbit Relay event metadata supports:

type EventMeta = {
  corrId?: string;
  causationId?: string;
  headers?: Record<string, string>;
  expectsReply?: boolean;
  timeoutMs?: number;
};

Metadata helpers

Example

import {
  withHeaders,
  withCorrelation,
  traceFrom,
} from "@bitspacerlabs/rabbit-relay";

// Start of a flow
const ev = withCorrelation(
  withHeaders(orderCreated(data), {
    tenantId: "tenant-1",
    source: "orders-service",
  }),
  "corr-123"
);

// Inside consumers
sub.handle("order.created", async (_id, ev) => {
  const next = paymentRequested(data, traceFrom(ev));
});

traceFrom(parent, extra?)

traceFrom() creates a child event from a parent event.

• preserves parent.meta.corrId if present
• otherwise uses parent.id as the correlation ID
• sets causationId to parent.id
• copies parent headers

You can merge extra metadata:

const child = paymentRequested(
  data,
  traceFrom(parent, {
    headers: {
      source: "payments-service",
    },
  })
);

Parent headers and child headers are merged.

Relationship with plugins

Plugins are still useful for process-wide tracing behavior.

Helpers are useful when you want explicit metadata in application code.

They work well together.

Summary

• Use withHeaders() for application headers
• Use withMeta() for full metadata control
• Use withCorrelation() for root correlation
• Use traceFrom() for child events
• Correlation and causation make event chains easier to debug