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.

eventhubs 的CreateReceiverAsync 类的API有一些重载的方法，其中有一少部分方法都带有叫“epoch”这个参数.这篇文章就详细解释一下这个epoch参数。

Public method   CreateReceiverAsync(String)  Asynchronous version of CreateReceiver(String).  
Public method   CreateReceiverAsync(String, DateTime)  Asynchronous version of CreateReceiver(String, DateTime).  
Public method   CreateReceiverAsync(String, Int64)  Asynchronous version of CreateReceiver(String, Int64).  
Public method   CreateReceiverAsync(String, String)  Asynchronous version of CreateReceiver(String, String).  
Public method   CreateReceiverAsync(String, DateTime, Int64)  Asynchronous version of CreateReceiver(String, DateTime, Int64).  
Public method   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.

下面说一下receive epoch是如何工作的：

有epoch：Receiver epoch的特性让用户能够保证在任一时间点，一个消费组只能有一个接收者，下面是一些规则：

a: 如果一个消费组没有任何的receiver，用户可以创建一个receiver，此时epoch的值可以为任何值；

b: 如果当前有一个receiver，它的epoch值是e1，此时再来一个新的receiver，它的epoch值为e2，如果e1<=e2,那么e1的receiver将会自动关闭连接，e2的receiver将会创建成功

c: 如果当前有一个receiver，它的epoch值是e1，此时再来一个新的receiver，它的epoch值为e2，如果e1>e2,那么e2的创建将会抛出“epoch 为e1的receiver已经存在”的错误

没有epoch：在流处理中有一些场景：就是用户想要在一个消费组上创建多个receiver，为了支持这些场景，我们能够不用epoch来创建receiver，在这种情况下，我们允许在一个消费组上最多有5个并发的receiver。

混合模式：你在同一个消费组上创建了一个带有epoch的receiver，然后又切换到了no-epoch 或者vice-versa，我们通常是不建议应用程序这么用的。尽管这样在应用程序测试的时候能生效，但需要按照如下的办法处理这种场景：

a: 如果已经创建了一个epoch为e1的receiver，并且正在接收事件，此时又创建了一个没有epoch的receiver，那么这个新的receiver将会创建失败，在系统中，带有epoch的receiver总是具有最高的优先级的

b: 如果已经有了一个epoch为e1的receiver断开连接了，然后在一个新MessagingFactory中创建了一个没有epoch的receiver，那么这个新的receiver将会创建成功。注意：系统将会在大约10分钟后检测到断开连接的receiver

c: 如果创建了一个或者多个没有epoch的receiver，然后又创建了一个epoch为e1的receiver，那么之前创建的receiver将会失去连接

译文地址：Event Hubs Receiver Epoch