Event Hubs Receiver Epoch

Event Hubs CreateReceiverAsync API has several overloads of which a few of them take a parameter named "epoch". This blog is to explain the details of this epoch parameter.

	CreateReceiverAsync(String)	Asynchronous version of CreateReceiver(String).
	CreateReceiverAsync(String, DateTime)	Asynchronous version of CreateReceiver(String, DateTime).
	CreateReceiverAsync(String, Int64)	Asynchronous version of CreateReceiver(String, Int64).
	CreateReceiverAsync(String, String)	Asynchronous version of CreateReceiver(String, String).
	CreateReceiverAsync(String, DateTime, Int64)	Asynchronous version of CreateReceiver(String, DateTime, Int64).
	CreateReceiverAsync(String, String, Int64)	Asynchronous version of CreateReceiver(String, String, Int64).

Here is how the receive epoch works:

With Epoch: Receiver epoch feature provides users ability to ensure that there is only one receiver on a consumer group at any point in time, with the following rules.

a)     If there is no existing receiver on a consumer group then user can create a receiver with any epoch value.

b)     If there is a receiver with epoch value e1 and a new receiver is created with an epoch value e2 where e1 <= e2 then receiver with e1 will be disconnected automatically, receiver with e2 get created successfully.

c)      If there is a receiver with epoch value e1 and a new receiver is created with an epoch value e2 where e1 > e2 then creation of e2 with fail with the error “A receiver with epoch e1 already exists”

No Epoch: There are some scenarios in stream processing where users would like to create multiple receivers on a single consumer group. To support such scenarios we do have ability to CreateReceiver without epoch and in this case we allow upto 5 concurrent receivers on the consumer group.

Mixed Mode: We usually don’t recommend application usage where you create a receiver with epoch and then switch to no-epoch or vice-versa on the same consumer group. Although this can happen during application testing, we handle the situation like this:

 a)      If there is a receiver already created with epoch e1 and is actively receiving events and a new receiver is created with no epoch , then the creation of new receiver will fail. Epoch receivers always take precedence in the system.

b)      If there was a receiver already created with epoch e1 and got is disconnected  and a new receiver is created with no epoch  on a new MessagingFactory, then the creation of new receiver will succeed. There is a caveat here that our system will detect the “receiver disconnection” after ~10 minutes.

c)      If there are one or more receivers created with no epoch and a new receiver is created with epoch e1 then all the old receivers get disconnected.