Apache Pulsar PIP-379 深度解析:Key_Shared 订阅的 Draining Hashes 与消息顺序保证机制

原创2026-10-08 18:19:071,444 阅读
文章标签:消息队列流处理后端微服务消息路由

Apache Pulsar PIP-379 深度解析:Key_Shared 订阅的 Draining Hashes 与消息顺序保证机制

本指南以 Apache Pulsar 仓库中的 PIP-379 提案 为核心,系统讲解 Key_Shared 订阅在消费者加入/退出时如何通过 "draining hashes"(排空哈希)概念确保"同一 key 的消息在同一时刻只交付给一个消费者"的顺序不变式。读者将掌握 PIP-379 的设计动机、新旧顺序保证契约的差异、七步实现方案的核心代码逻辑、相关的 Broker 配置参数与可观测性指标,并了解其与 PIP-282 "recently joined consumers" 方案的演进关系。

背景:Key_Shared 订阅模式与顺序保证契约的演进

Apache Pulsar 的 Key_Shared 订阅模式(SubType.Key_Shared)在按 key 维度保证消息顺序的前提下,允许多个消费者并行消费,适合"特定 key 的消息必须有序,但整体吞吐可以通过多消费者并行提升"的场景。

理解 PIP-379 之前,需要先掌握三个核心概念:

  • Key_Shared 订阅:按 key 维持消息顺序、同时允许多个消费者的订阅模式;
  • 哈希范围(Hash ranges):在 AUTO_SPLIT 模式下,哈希空间被划分给活跃消费者以分发消息处理任务;
  • Pending messages(待确认消息):已发送给消费者但尚未 ack 的消息(也称 "pending acks" 或 "unacknowledged messages")。

新旧 "Preserving order" 契约对比

PIP-379 修改了 Key_Shared 官方文档中 "Preserving order of processing" 一节的内容。先看 Pulsar 3.x(PIP-282 之前) 的表述:

Key Shared 订阅类型保证一个 key 在同一时刻只会被一个消费者处理。当新消费者连接时,部分 key 的映射会从现有消费者转移到新消费者。连接建立后,broker 会记录当前 read position 并关联到新消费者。broker 只有在 read position 之前的所有消息都被 ack 后,才会向新消费者投递消息……

而 master 分支(Pulsar 4.0,PIP-282 版本) 的表述几乎一致,只是把 "read position" 换成了 lastSentPosition(PIP-282 对 "recently joined consumers" 位置定义的重构)。

PIP-379 指出:这种契约是"方案导向"的——它先描述一个解决方案,再把保证与这个方案绑定,让人误以为"只要方案能处理,就有保证"。而契约本身应该是一个与实现解耦的不变式(invariant)。

Motivation:现有实现的六大挑战

PIP-379 提出的动机围绕当前 Key_Shared 实现的六个具体问题:

  1. 顺序保证契约复杂且含根本性问题:契约难以理解,把保证与特定解决方案绑定;
  2. 契约履行不完整:在消费者变更期间(如滚动重启场景),当前实现难以始终阻止消息在原消费者存在 pending 时被发送给其他消费者——issue #23307 报告了该乱序 corner case;
  3. 可用性问题:排查"消息为什么被阻塞"耗时且困难;
  4. 不必要的消息阻塞:任意哈希范围被阻塞时,当前实现会阻塞所有消息的投递,即使其他 key 本可独立处理,导致消费者利用率下降、延迟升高;
  5. 可观测性不足:消费状态卡住时缺乏清晰可见的状态,难以构建自动化检测与缓解手段;
  6. 复杂度:管理 "recently joined consumers" 的既有方案过于复杂,难以维护和调试。

In Scope 与 Out of Scope

PIP-379 的目标范围明确限定:

  • 范围内:澄清并履行 Key_Shared AUTO_SPLIT 模式的 key 顺序投递契约;修复乱序与"同一 key 同时在多个消费者 outstanding"的问题;改进未确认消息处理避免无限阻塞;消除 PIP-282 的 "sent positions" 跟踪以降低内存占用;实现 "draining hashes";提升可靠性、可用性、可扩展性与可观测性;保证消费者变更期间同一 key 的严格顺序。
  • 范围外:不修改 Exclusive、Failover、Shared 等其他订阅类型;不为 negative acknowledgements(负确认)场景增加 key 级顺序保证。

更新后的顺序保证契约(PIP-379 核心)

PIP-379 将文档契约更新为一句简洁、可独立验证的陈述:

在 Key_Shared 订阅中,具有相同 key 的消息在同一时刻只允许交付给一个消费者,且只允许在该消费者上处于未确认状态。

补充说明:

  • 当新消费者加入或离开(默认 AUTO_SPLIT 模式下 key 的消费者映射会变化)时,只有在该 key 的所有 pending 消息被 ack、或原消费者断开连接之后,key 的归属才允许切换;
  • Key_Shared 不禁止任何 consumer API 的使用,例如 negativeAcknowledge 或 redeliverUnacknowledgedMessages。这些方法触发的消息会尽快重投,虽然不保证顺序,但"同一 key 同一时刻只交付给一个消费者"的保证仍然成立。

计算机科学视角:不变式(Invariant)

从计算机科学视角看,上述契约正是 invariant 的定义——"在程序执行的某个阶段始终为真的逻辑断言"。PIP-379 的设计与实现全部围绕确保这个不变式始终成立展开。

负确认场景的未来工作

更新后的契约明确承认:使用负确认时无法保留 key 级顺序。这在 PIP-379 范围内不解决。文档指出一个潜在未来方案:客户端在负确认某条消息时,同时拒绝接收同 key 的后续消息,直到原消息被重新投递;而真正完备的方案需要 broker 侧支持——当存在 pending 的负确认消息时,阻塞该 key 的进一步投递,直到该 key 的所有负确认消息被消费者 ack。这一未来实现可以建立在 PIP-379 的 "draining hashes" 概念之上进行扩展。

高层设计:七步实现方案

PIP-379 的解决方案核心是引入 "draining hashes"(排空哈希) 概念。当消费者哈希范围变化时,受影响范围内 pending 消息的哈希被登记到 "draining hashes" 集合中;这些哈希上的后续消息投递被阻塞,直到 pending 消息全部处理完毕(引用计数归零)。整个生命周期可拆解为七个步骤:

步骤 1:消费者哈希范围变化时登记 draining hashes

当消费者加入或离开、哈希范围发生变更时,遍历受影响消费者的 pending 消息,若 pending 消息的哈希属于受影响范围,则将该哈希加入 draining hashes 跟踪器。

仓库中 PersistentStickyKeyDispatcherMultipleConsumers.java 的 registerDrainingHashes 是实际实现(ImpactedConsumersResult.processUpdatedHashRanges 提供了每个消费者受影响的哈希范围及操作类型 ADD/REMOVE):

private synchronized void registerDrainingHashes(Consumer skipConsumer,
                                                 ImpactedConsumersResult impactedConsumers) {
    impactedConsumers.processUpdatedHashRanges((c, updatedHashRanges, opType) -> {
        if (c != skipConsumer) {
            c.getPendingAcks().forEach((ledgerId, entryId, batchSize, stickyKeyHash) -> {
                if (stickyKeyHash == STICKY_KEY_HASH_NOT_SET) { ... return; }
                if (updatedHashRanges.containsStickyKey(stickyKeyHash)) {
                    switch (opType) {
                        // reduce ref count in case the stickyKeyHash was re-assigned to the original consumer
                        case ADD -> {
                            var entry = drainingHashesTracker.getEntry(stickyKeyHash);
                            if (entry != null && entry.getConsumer() == c) {
                                drainingHashesTracker.reduceRefCount(c, stickyKeyHash, false);
                            }
                        }
                        // add the pending ack to the draining hashes tracker if the hash is in the range
                        case REMOVE -> drainingHashesTracker.addEntry(c, stickyKeyHash);
                    }
                }
            });
        }
    });
}

PIP-379 文档中的代码示例还展示了一个关键性能优化:将范围集合转换为数组以避免 pending acks 循环中的迭代器分配,且由于范围有序,一旦当前范围的起点大于 stickyKeyHash 即可提前 break,停止检查后续范围。

步骤 2:draining 状态下的哈希阻塞后续消息投递

对处于 "draining hashes" 集合中的哈希,后续消息在投递前被拦截。分发器在 canDispatchEntry 中调用 shouldBlockDispatch,最终委托给 DrainingHashesTracker.shouldBlockStickyKeyHash:

// If the hash is draining, do not send the message
return drainingHashesRequired && drainingHashesTracker.shouldBlockStickyKeyHash(consumer, stickyKeyHash);

步骤 3:引用计数器跟踪每个 draining 哈希的 pending 消息数

每个 draining 哈希对应一个 DrainingHashEntry,内部维护 refCount(该哈希的 pending 消息数)与 blockedCount(因该哈希被阻塞的投递尝试次数)。仓库实现中两者均使用 AtomicIntegerFieldUpdater 进行原子更新:

// optimize the memory consumption of the map by using primitive int keys
private final Int2ObjectOpenHashMap<DrainingHashEntry> drainingHashes = new Int2ObjectOpenHashMap<>();

public static class DrainingHashEntry {
    private final Consumer consumer;
    private volatile int refCount;
    private volatile int blockedCount;

    public Consumer getConsumer() { return consumer; }
    void incrementRefCount() { REF_COUNT_UPDATER.incrementAndGet(this); }
    boolean decrementRefCount() { return REF_COUNT_UPDATER.decrementAndGet(this) == 0; }
    void incrementBlockedCount() { BLOCKED_COUNT_UPDATER.incrementAndGet(this); }
    boolean isBlocking() { return blockedCount > 0; }
}

内存占用估算

PIP-379 文档给出了精确的内存模型估算(单条记录约 52 字节,其中 key 为对象头 16 字节 + int 4 字节 = 20 字节,entry 为对象头 16 字节 + long 8 字节 + int 4 字节 + int 4 字节 = 32 字节)。为容纳内存对齐与 Int2ObjectOpenHashMap 的额外开销,实际计算按每条 80 字节计。消费者变更后每个订阅的内存占用:

  • 最坏情况(全部 64k 个哈希同时 draining):约 5MB;
  • 实际常见情况(少于 1000 个哈希 draining):小于 80KB;
  • 10000 个 draining 哈希:约 800KB。

当所有哈希排空、不再阻塞后,draining 跟踪的内存占用归零——它不是常态开销,只在转换期存在。

哈希范围从 2^31-1 缩减到 65535

为降低最坏情况内存占用,ConsistentHashingStickyKeyConsumerSelector 的哈希范围从 Integer.MAX_VALUE(2^31-1)缩减为 65535(2^16-1)。仓库中 StickyKeyConsumerSelector 接口的 DEFAULT_RANGE_SIZE = 2 << 15(即 65536),StickyKeyConsumerSelectorUtils.makeStickyKeyHash 使用 Murmur3_32Hash 对 sticky key 取哈希后对范围取模,并特意规避 STICKY_KEY_HASH_NOT_SET(0)这个特殊值。PIP-379 断言:缩减哈希范围不会显著影响消息在消费者间的分布精度。

步骤 4:消息 ack 或消费者断开时递减引用计数

单个 ack 在 Consumer.removePendingAcks 中处理——先尝试从对应消费者的 PendingAcksMap 移除该位置;若消息已被其他消费者移除则返回 false:

private boolean removePendingAcks(Consumer ackOwnedConsumer, Position position) {
    PendingAcksMap ownedConsumerPendingAcks = ackOwnedConsumer.getPendingAcks();
    if (!ownedConsumerPendingAcks.remove(position.getLedgerId(), position.getEntryId())) {
        // Message was already removed by the other consumer
        return false;
    }
    ...
}

PendingAcksMap.remove 内部通过 PendingAcksMap.PendingAcksRemoveHandler 回调 handleRemoving,触发 DrainingHashesTracker 中的同步递减。分发器在 handleConsumerAdded 中注册该回调:

consumer.setPendingAcksRemoveHandler(new PendingAcksMap.PendingAcksRemoveHandler() {
    @Override
    public void handleRemoving(Consumer consumer, long ledgerId, long entryId, int stickyKeyHash,
                               boolean closing) {
        drainingHashesTracker.reduceRefCount(consumer, stickyKeyHash, closing);
    }
    @Override
    public void startBatch() { drainingHashesTracker.startBatch(); }
    @Override
    public void endBatch() { drainingHashesTracker.endBatch(); }
});

消费者断开时,PersistentDispatcherMultipleConsumers.removeConsumer 流程会调用 pendingAcks.forEachAndClose,把 pending 消息重新加入 replay 队列;forEachAndClose 在处理每条记录后同样通过 handleRemoving 回调同步 DrainingHashesTracker。这种"回调解耦"的设计遵循 separation of concerns(关注点分离) 原则:DrainingHashesTracker 与 PendingAcksMap 各司其职,无需把 draining 逻辑塞进 PendingAcksMap。

步骤 5:引用计数归零后移除哈希并解除阻塞(含批量通知)

DrainingHashesTracker.reduceRefCount 在引用计数归零时移除哈希,若该哈希曾经阻塞过投递(isBlocking() 为 true),则通过 unblockingHandler.stickyKeyHashUnblocked(stickyHash) 通知分发器重新调度读取:

public synchronized void reduceRefCount(Consumer consumer, int stickyHash) {
    DrainingHashEntry entry = drainingHashes.get(stickyHash);
    if (entry == null) return;
    if (entry.decrementRefCount()) {
        DrainingHashEntry removed = drainingHashes.remove(stickyHash);
        if (removed.isBlocking()) {
            unblockingHandler.stickyKeyHashUnblocked(stickyHash);
        }
    }
}

通知由分发器的 stickyKeyHashUnblocked 处理,它会调用 reScheduleReadInMs(keySharedUnblockingIntervalMsSupplier.getAsLong())——即把多次解阻塞事件批量合并为一次重调度,而不是每个哈希一次通知。仓库中该逻辑封装在 RescheduleReadHandler 中,通过 compareAndSet 防止重复调度,到期后调用 readMoreEntries() 恢复投递。

关键配置参数:批量通知的间隔由 ServiceConfiguration.keySharedUnblockingIntervalMs 控制,默认 10L 毫秒,属于 CATEGORY_POLICIES 分类且支持动态更新(dynamic = true)。配置说明指出:设置该延迟的原因正是为了批量合并多个 unblocking 事件,避免每个事件都单独触发一次重投。

步骤 6:哈希重新分配给原消费者时的"惰性"解除

消费者哈希分配可能多次变化,一个 draining 哈希有可能重新回到原消费者名下。DrainingHashEntry 保存了 draining 消费者的信息:当投递尝试发生时,如果目标消费者就是 draining 消费者,则无需阻塞,且应将该哈希从 draining 集合中移除。这种"惰性"策略避免了在哈希分配变化时主动扫描所有 draining 哈希:

public synchronized boolean shouldBlockStickyKeyHash(Consumer consumer, int stickyKeyHash) {
    DrainingHashEntry entry = drainingHashes.get(stickyKeyHash);
    // if the entry is not found, the hash is not draining. Don't block the hash.
    if (entry == null) return false;
    // hash has been reassigned to the original consumer, remove the entry and don't block the hash
    if (entry.getConsumer() == consumer) {
        drainingHashes.remove(stickyKeyHash, entry);
        return false;
    }
    // increment the blocked count which is used to determine if the hash is blocking
    entry.incrementBlockedCount();
    // block the hash
    return true;
}

步骤 7:发送过程中的竞态条件防护

当消费者在读取与发送进行中加入/移除、哈希范围变化时,存在把本应阻塞的消息投递出去的竞态风险。PIP-379 的应对是:在消息加入 pending acks 映射时执行二次校验,并对 pending acks 处理增加额外锁。

PendingAcksMap.addPendingAckIfAllowed 是核心防护点(PendingAcksMap.java):

public boolean addPendingAckIfAllowed(long ledgerId, long entryId, int batchSize, int stickyKeyHash) {
    try {
        writeLock.lock();
        // prevent adding sticky hash to pending acks if the PendingAcksMap has already been closed
        // and there's a race condition between closing the consumer and sending new messages
        if (closed) return false;
        // prevent adding sticky hash to pending acks if it's already in draining hashes
        // to avoid any race conditions that would break consistency
        PendingAcksAddHandler pendingAcksAddHandler = pendingAcksAddHandlerSupplier.get();
        if (pendingAcksAddHandler != null
                && !pendingAcksAddHandler.handleAdding(consumer, ledgerId, entryId, stickyKeyHash)) {
            return false;
        }
        Long2ObjectSortedMap<IntIntPair> ledgerPendingAcks =
                pendingAcks.computeIfAbsent(ledgerId, k -> new Long2ObjectRBTreeMap<>());
        ledgerPendingAcks.put(entryId, IntIntPair.of(batchSize, stickyKeyHash));
        return true;
    } finally {
        writeLock.unlock();
    }
}

该方法由 Consumer.sendMessages 调用;返回 false 时,该条消息被跳过投递(totalEntries--、释放 entry)。PendingAcksAddHandler 回调映射到分发器的 handleAddingPendingAck(PersistentStickyKeyDispatcherMultipleConsumers.java):

  • 若目标哈希正被另一个消费者 draining,则记录 warn 日志、把消息加入 replay 队列并阻止发送;
  • 若在 Normal 读取中该哈希已在 replay 队列(redeliveryMessages.containsStickyKeyHash),同样加入 replay 并阻止发送——这保证了"刚进入重投队列的消息必须先于后续消息被投递"的顺序要求。

这套双重防护确保消费者增减与哈希范围变化期间,pending acks 的视图始终一致,draining hashes 的跟踪也随之保持一致。

方案总结:只在转换期付出代价

PIP-379 的高层设计在满足新契约的同时把性能与内存影响降到最低:draining 跟踪只在转换状态(消费者加入/离开的过渡期)起作用。当消费者长期稳定连接、所有 draining 哈希被清除后,投递路径无需检查任何特殊规则、无需维护额外状态;draining hashes 为空时,查找基本是 no-op,不消耗 CPU 与内存资源。

公共面变更:Topic Stats 与可观测性

移除 PIP-282 的统计字段

PIP-282 "recently joined consumers"/"last sent position" 方案对应的 topic stats 字段被移除:

  • 每个消费者的 lastSentPositionWhenJoining 字段;
  • 每个 Key_Shared 订阅的 consumersAfterMarkDeletePosition 字段;
  • 每个 Key_Shared 订阅的 individuallySentPositions 字段。

新增 draining hashes 统计

新的 topic stats 用于在订阅级和消费者级监控 "draining hashes" 功能(见 ConsumerStatsImpl.java 与 DrainingHashImpl.java 的对应字段):

  1. draining_hashes_count:当前处于 draining 状态的哈希数量(ConsumerStatsImpl.drainingHashesCount);
  2. draining_hashes_pending_messages:所有 draining 哈希的 pending 消息总数(drainingHashesUnackedMessages);
  3. draining_hashes_cleared_total:累计从 draining 状态清除的哈希总数(drainingHashesClearedTotal);
  4. draining_hashes:哈希级明细(放在消费者级以减少信息冗余),包含:
    • hash:哈希值;
    • 该哈希的 pending 消息数(unackMsgs);
    • blockedAttempts:该哈希阻塞投递尝试的次数(仓库实现中额外提供的字段,见 DrainingHashImpl)。

在仓库的 DrainingHashesTracker.updateConsumerStats 中,这些统计通过 ConsumerDrainingHashesStats(内部使用 LongBitmap 跟踪每个消费者的 draining 哈希集合、以 drainingHashesClearedTotal 累积清除计数)汇总到 ConsumerStatsImpl,再在 PersistentSubscription 中累加到订阅级统计。需要注意的是,该类使用读写锁确保线程安全,并把对外的副作用(如统计更新、解阻塞通知)放到写锁之外执行,以避免早期版本中"消费者操作与 topic stats 请求并发导致死锁"的问题(该死锁修复见仓库注释中引用的 #23854)。

此外,PIP-379 还提出考虑新增一个独立 REST API 列出消费者全部 pending 消息,以便查询哪些消息属于某个 draining 哈希、精确识别"拽住某个哈希、阻塞投递给其他消费者"的消息 ID——这是可观测性增强的后续方向。

向后与向前兼容性

"draining hashes" 特性本身不引入向后或向前兼容问题:状态全部在运行时处理,改动集中在 broker 侧,不改变客户端协议。

一个与 PIP-379 略有相关但必要的保障:由于 PIP-282 也是 Pulsar 4.0.0 的新特性,需要提供一个特性开关(feature flag),让从 Pulsar 3.x 升级的用户在 PIP-379 引发可能的回归时,可以回退到 PIP-282 之前的 "recently joined consumers" 逻辑。该开关的具体实现细节在对应 PR 中落地。

与 PIP-282 的关系:从位置标记到哈希排空

PIP-379 是对 PIP-282 方案的替代与简化。PIP-282(pip/pip-282.md)解决的是 "recently joined consumers" 使用 read position 作为加入位置导致的乱序问题——它引入了 lastSentPositionWhenJoining 与逐 key 的 lastSentPosition 跟踪,本质是"记录每个消费者/每个 key 最后一次发送的位置,新消费者必须等这些位置之前的消息全部 ack 才能开始收消息"。

PIP-379 的视角更彻底:与其追踪"每个位置发到哪了",不如直接追踪哪些哈希上还有 pending 消息、这些哈希目前归谁。只要一个哈希上有 pending 消息且归属发生过变化,该哈希就进入 draining 状态并阻塞新投递,直到 pending 清空。这使得:

  • 内存占用从"每个消费者 × 每个 key 位置"的跟踪,降级为"每个 draining 哈希一个 52 字节条目"的稀疏跟踪(默认情况下近乎为零);
  • 语义从"复杂的最近加入者位置管理"简化为"不变式:同一 key 的消息同一时刻只允许一个消费者持有 pending";
  • 消除了 PIP-282 方案的 lastSentPositionWhenJoining、consumersAfterMarkDeletePosition、individuallySentPositions 等统计字段。

源码阅读路线图

如果希望深入验证本文的结论,可以在当前仓库中按以下路径阅读:

相关 Broker 配置速查

在 conf/broker.conf 中可以查看与 Key_Shared 相关的既有配置(PIP-379 新增的 keySharedUnblockingIntervalMs 目前仅存在于 ServiceConfiguration 源码中,可通过动态配置或 broker 配置注入):

配置项 默认值 说明
subscriptionKeySharedUseConsistentHashing true AUTO_SPLIT 模式下使用 consistent hashing(而非范围切分)来向新消费者重新分配 key(conf/broker.conf)
subscriptionKeySharedConsistentHashingReplicaPoints 100 consistent-hashing 环上的虚拟节点数,越高 key 分配越均衡
keySharedLookAheadMsgInReplayThresholdPerConsumer 4000 每个消费者在 replay 队列中的 look-ahead 消息阈值(0 表示禁用该限制)
keySharedLookAheadMsgInReplayThresholdPerSubscription 40000 每个订阅的 look-ahead 阈值,生效阈值取 min(perConsumer × consumerCount, perSubscription)
keySharedUnblockingIntervalMs 10 阻塞哈希解阻塞后,批量触发重投的延迟间隔(PIP-379 新增,动态可调)

其中两个 look-ahead 配置在 PersistentStickyKeyDispatcherMultipleConsumers.getEffectiveLookAheadLimit 中有精确的计算逻辑:当两者均无效(≤0)时,会回退到 maxUnackedMessagesPerSubscription 与 maxUnackedMessagesPerConsumer × consumerCount 的最小值。look-ahead 机制确保在哈希被阻塞、无法推进时,broker 仍能继续读取后续消息投递给其他消费者,而不是整个订阅停滞。

结语

PIP-379 通过引入 "draining hashes" 概念,把 Key_Shared 订阅的顺序保证从"复杂的位置跟踪方案"重构为"一个始终成立的不变式"——同一 key 的消息同一时刻只交付给一个消费者。它修复了消费者变更期间的乱序 corner case,消除了全量消息阻塞造成的吞吐损失,用稀疏的引用计数结构把过渡期内存占用控制在可忽略水平,并通过新增的 draining hashes 统计让"卡住的原因"一目了然。对于在 Pulsar 4.0 上使用 Key_Shared AUTO_SPLIT 模式的用户而言,理解这套机制是正确配置、排查乱序与性能问题的前提。

登录后查看全文
pulsar