Correlation ids

In order to provide a mechanism that you can use to track cause and effect in your event-driven systems, Rebus supports automatic flow of correlation IDs.

This means that Rebus will automatically come up with a new GUID correlation ID whenever you send or publish a message and

• a correlation ID has not been provided by you explicitly
• a correlation ID could not be found in the current message context

which will be put in the rebus-correlation-id header of the outgoing transport message.

If, however, you perform any kind of send operation (i.e. send, publish, and reply) from within a message handler, and the current message context has a correlation ID in its headers, then the correlation ID will automagically be transferred to the outgoing message.

So how do I put this to use?

One thing that has proven to be useful is to use the correlation ID of an incoming message as a context variable in your logging framework - e.g. with Log4Net, you'd set ThreadContext.Properties["CorrelationId"] = correlationIdOfMessageBeingHandled in the BeforeTransportMessage Rebus hook, allowing the logger to include the ID in each emitted log line by having %property{CorrelationId} in its layout.

In fact, this mechanism has proven to be so useful that Rebus' Log4Net integration allows you to go

Configure.With(...)
    .Logging(l => l.Log4Net())
    .TransferCorrelationIdToLog4NetThreadContext("MyCorrelationId")
    .(...)

in order to have the MyCorrelationId property set on Log4Net's thread context.

This way, when you're querying across all of your log files to track why something happened, you can easily backtrack events and figure out where and why something happened.