Correlation id

A correlation id relates messages to each other. It's sticky: when a handler receives a message with a correlation id, every message it sends or publishes gets the same one. This page shows how to set and read it.

Correlation ids are useful for logging and tracing a flow of messages through the system. Every log written while handling the messages of one request can carry the same id.

import { Bus, handlerFor } from '@node-ts/bus-core'
import { messageTypes } from './message-types.generated'
import { ChargeCreditCard, CreditCardCharged } from './messages'

const bus = Bus.configure()
  .withMessageTypes(messageTypes)
  .withHandler(
    handlerFor(ChargeCreditCard, async (command, attributes, ctx) => {
      console.log('Charging card', { correlationId: attributes.correlationId })
      // CreditCardCharged gets the command's correlation id
      await ctx.publish(
        new CreditCardCharged(
          command.creditCardToken,
          command.amount,
          new Date()
        )
      )
    })
  )
  .build()

await bus.initialize()
await bus.start()

await bus.send(new ChargeCreditCard('tok_visa', 1200), {
  correlationId: 'cd091b26-f0e6-43fb-9962-c06786948e26'
})

Here, a ChargeCreditCard command is sent with the correlation id cd091b26-f0e6-43fb-9962-c06786948e26. Its handler publishes CreditCardCharged, which gets the same correlation id, and so does anything sent while handling that.

A message sent outside a handler without a correlation id gets a new one. Handlers can also read it from their context, as ctx.correlationId.

See also

• Sticky attributes, which propagate the same way
• Middleware, to add the correlation id to every log