Redis Stream 怎样查看消费者组待处理消息

Redis Stream 消费者组里，所谓“待处理消息”不是 Stream 中所有还存在的消息，而是已经被某个消费者读到、进入 Pending Entries List（PEL）、但还没有被 XACK 确认的消息。查看这类消息时，先用不带范围参数的 XPENDING 看摘要，再用带范围和 COUNT 的形式取明细。

官方地址：https://redis.io/docs/latest/commands/xpending/

下面的示例使用 Stream 键 orders、消费者组 workers 和消费者 worker-1。示例命令用于说明语法和判断方式，文中的返回值是结构化示意，不代表本文已经连接过你的 Redis 实例。

先弄清楚 XPENDING 查的是什么

消费者组读取消息后，Redis 会把消息 ID 与当前消费者、空闲时间、投递次数等信息放进该组的待处理列表。只有消费者确认消息后，这条记录才会从 PEL 中移除；Stream 本身的消息是否删除，是另一个由 XDEL、裁剪策略或保留策略决定的问题。

# 创建一个消费者组；$ 表示从创建时的新消息开始读。
redis-cli XGROUP CREATE orders workers $ MKSTREAM

# 消费者读取后，消息进入 workers 组的待处理列表。
redis-cli XREADGROUP GROUP workers worker-1 COUNT 2 STREAMS orders >

# 业务处理成功后确认消息，PEL 中对应记录才会减少。
redis-cli XACK orders workers 1710000000000-0

因此，XLEN orders 只能回答 Stream 里有多少条消息，不能回答“workers 组还有多少条已经投递但未确认”。要看消费者组积压，入口应该是 XPENDING orders workers。

不带范围时，先看待处理摘要

最短的查询形式如下：

# 只看 workers 组的待处理概况，不拉取每一条消息。
redis-cli XPENDING orders workers

摘要通常包含四类信息：待处理总数、最小待处理消息 ID、最大待处理消息 ID，以及按消费者汇总的数量。它适合放在排障第一步或监控采样里：总数为零时，通常表示当前没有未确认的 PEL 记录；总数上升时，再继续查明细。

最小和最大 ID 只是 PEL 的范围边界。判断是否有消费者失联，还要结合明细里的空闲时间、应用心跳和部署状态，不能只看消费者名称。

用范围和 COUNT 定位具体待处理消息

要列出具体记录，使用起始 ID、结束 ID 和数量上限：

# - 到 + 表示扫描整个待处理 ID 范围；COUNT 10 限制本次返回数量。
redis-cli XPENDING orders workers - + COUNT 10

# 只看 worker-1 名下的待处理记录，便于判断单个消费者是否卡住。
redis-cli XPENDING orders workers - + COUNT 10 worker-1

# 只找空闲时间至少 60 秒的记录；时间单位是毫秒。
redis-cli XPENDING orders workers IDLE 60000 - + COUNT 10

明细结果通常按“消息 ID、消费者、空闲时间、投递次数”组织。这里的 IDLE 是筛选条件，不是把消息排序成最空闲优先；想做稳定的批量处理，仍应使用明确的起始 ID、结束 ID 和较小的 COUNT。

查询时有三个容易写错的点：

• XPENDING key group 里的 group 是消费者组名，不是消费者名。
• 消费者筛选放在 COUNT 后面，写错位置会导致命令参数不符合语法。
• - 和 + 是全范围边界；生产排障不一定要每次扫描完整 PEL。

空闲时间变大后，什么时候应该转交

空闲时间长，说明消息自上次投递以来一直没有被确认，但它不自动证明原消费者已经崩溃。可能的原因包括业务处理很慢、消费者正在重试、网络连接中断，或者确认动作没有落库。转交前应先定义阈值，并确认同一条消息不会被两个消费者同时执行产生副作用。

# Redis 6.2+：把空闲时间达到阈值的消息交给 worker-2。
# 0-0 是扫描起点，COUNT 10 限制单次处理量。
redis-cli XAUTOCLAIM orders workers worker-2 60000 0-0 COUNT 10

# 已知具体消息 ID 时，也可以显式转交一条或几条记录。
redis-cli XCLAIM orders workers worker-2 60000 1710000000000-0

# worker-2 成功处理后再确认，避免只转交不收敛。
redis-cli XACK orders workers 1710000000000-0

XAUTOCLAIM 按最小空闲时间寻找并改变消息归属，适合从一批长期空闲记录中逐步接管；XCLAIM 更适合已经知道具体 ID 的场景。二者都不是“删除待处理记录”的命令，最终是否从 PEL 消失仍取决于新的消费者执行 XACK。

把 XPENDING 查询接入排障时的取舍

在值班脚本里，可以把查询拆成“摘要采样”和“明细抽样”两层。摘要只关心总数和按消费者的分布；只有总数持续超过阈值，或某个消费者的空闲时间超过业务阈值，才按小批量取明细。这样既能发现积压，也不会因为一次性拉取巨大 PEL 而放大 Redis 和网络压力。

# 第一层：适合周期性采样的轻量摘要查询。
redis-cli --raw XPENDING orders workers

# 第二层：只取一小批长期空闲记录，交给人工或恢复程序判断。
redis-cli --raw XPENDING orders workers IDLE 300000 - + COUNT 20

当你记录指标时，建议至少区分：待处理总数、最长空闲时间、每个消费者的待处理数、转交次数和确认失败次数。不要把 XPENDING 的总数直接当作 Stream 长度，也不要把一次转交成功当作业务处理成功。

常见问题

为什么 Stream 里还能看到消息，但 XPENDING 没有它？ 因为 Stream 存储和消费者组 PEL 是两个维度。消息可能还保留在 Stream 中，却已经被确认；也可能消息被裁剪后，PEL 中仍需要通过待处理记录判断是否需要清理或恢复。

XPENDING 返回零，是否代表没有新消息？ 不是。它只表示该消费者组当前没有已投递但未确认的记录；Stream 仍可能有尚未被该组读取的新消息。

应该先 XCLAIM 还是先 XACK？ 对长期空闲且确认不会重复执行的消息，通常先转交给恢复消费者，完成幂等处理后再 XACK。直接 XACK 会移除待处理记录，但不会替你完成业务处理。

归纳起来，查看 Redis Stream 消费者组待处理消息的顺序是：先用 XPENDING key group 看摘要，再用范围、COUNT、消费者或 IDLE 筛出明细；只有确认原因和幂等边界后，才用 XAUTOCLAIM/XCLAIM 转交，并在处理完成后用 XACK 收口。