Redis Streams 怎样按消息 ID 查询消费积压

按消息 ID 查 Redis Streams 的消费积压，先确定 stream key 和消费者组，再用 XPENDING 的起止 ID 查询已投递但未确认的记录；如果想看还没投递给该组的消息数量，应看 XINFO GROUPS 的 lag。消息 ID 是范围定位依据，不能把两个 ID 相减当作积压条数。

这里把查询设计为“组选取、范围过滤、明细展开”三个任务，适合命令行排查，也便于实现监控面板。官方命令入口：https://redis.io/docs/latest/commands/xpending/。示例假设已有 stream jobs:events、消费者组 workers；命令不负责创建它们，不涉及接管或确认消息。

用户任务：先区分两种待处理状态

PEL 是消费者组的待确认列表。消息通过组被投递、且没有跳过确认跟踪时，会产生 pending 记录；业务完成后通常再确认。lag 则描述尚未投递给该组的消息数量，不是 PEL 的别名。一个组可能 lag 为零，但仍有很多已投递消息没有确认。

# 在已配置好连接的环境中执行，查看各组名称、pending和投递位置。
redis-cli XINFO GROUPS jobs:events

# 读取workers组的PEL摘要，不会推进投递位置。
redis-cli XPENDING jobs:events workers

摘要包含 pending 总量、最小及最大 pending ID，并列出有 pending 的消费者及其数量。不能把最小 pending ID 当作组的 last-delivered-id，更不能把 last-delivered-id 当成“业务已全部完成的位置”。确认可以乱序发生。

查询拆解：消息 ID 区间、消费者和空闲时间

XPENDING 的详细形式需要 start、end 和 count。两个边界默认包含端点；减号和加号分别表示最小与最大位置。下面的数值 ID 仅演示写法，要换成真实排查范围。

# 查看整个PEL里最前面的至多20条，不是取20条新消息。
redis-cli XPENDING jobs:events workers - + 20

# 闭区间筛选，包含两个端点。
redis-cli XPENDING jobs:events workers 1700000000000-0 1700000005000-0 20

# 最后的worker-a是消费者名，只查它名下的待确认条目。
redis-cli XPENDING jobs:events workers - + 20 worker-a

# IDLE单位为毫秒；60000表示至少60秒未再次投递。
redis-cli XPENDING jobs:events workers IDLE 60000 - + 20

明细通常包含消息 ID、消费者、距上次投递的毫秒数和投递次数。空闲时长不是消息从生产到现在的年龄；重新投递可能改变它。投递次数也不是业务失败次数，不能直接用这个数判定已经失败多少次。

IDLE 和排他区间从 Redis 6.2 起支持；XINFO GROUPS 的 entries-read、lag 从 Redis 7.0 起提供。面板对旧版本字段缺失与命令不支持应显示明确说明，不能一律补零。

明细实现：查正文和翻页用不同的命令

XPENDING 查询的是 PEL 元数据，不返回消息字段。拿到一个 ID 后，用 XRANGE 把起止设为相同值读取对应正文。XRANGE 不接收消费者组，所以正文存在并不说明该组还未确认。

# 两个相同ID表示精确读取这一条消息的字段。
redis-cli XRANGE jobs:events 1700000000000-0 1700000000000-0

# 假设上一页最后一个pending ID为下面这个值，左括号表示排除它。
# 在shell里给左括号参数加引号，避免被当作shell语法。
redis-cli XPENDING jobs:events workers '(1700000002000-0' + 20

# 若实际last-delivered-id为1700000003000-0，查看其后仍保留的消息样本。
# 这是范围浏览，不是对该组进行投递。
redis-cli XRANGE jobs:events '(1700000003000-0' + COUNT 20

分页时使用本次返回的最后一个 ID 作为下一页排他起点，保留原来的 end、IDLE 和消费者过滤条件。不要手工把毫秒部分加一，否则可能跳过同一毫秒下序号更大的消息。

浏览 last-delivered-id 之后的条目有助于查看未投递区域，但多次查询期间消费者仍可能推进位置。它与之前读取的 lag 不是同一原子快照，也不能把“这一页返回二十条”当成全部积压恰好二十条。

结果可读性：把未知和截断显示出来

排查页面至少应同时呈现 stream、group、ID 区间、消费者过滤和采样时间。空闲时长标明毫秒或换算后的秒数，投递次数单独显示。pending 与 lag 使用文字标签区分，不能只靠两种颜色表达含义。

COUNT 只是单次返回上限。达到上限时，可以提供“继续查询”入口，并显示当前页起止 ID；没有拿到完整范围前，不要把当前页长度标成总数。lag 为 NULL 应显示“暂不可确定”，而不是“无积压”。

性能检查与边界状态

限制单次 count，避免一次拉完整个大 PEL。带 IDLE 的查询还可能扫描未满足条件的条目，所以返回很少不等于扫描很少。大量展开正文也会增加请求量，宜按需要读取。

删除或裁剪可能使 PEL 所指向的消息正文已不存在，具体保留行为还受命令和版本影响。XRANGE 返回空时，需区分正文不在与从未 pending，不能从一个空结果直接断言消费成功。组位置被人为调整或中间消息被删除等情况，也可能让 lag 暂时无法计算。

XPENDING、XINFO GROUPS 与 XRANGE 是观察手段。不要为了一次排查改用 XREADGROUP 读取新消息，也不要随手 XACK 把列表清空；这些操作会改变消费状态，已经超出查询任务。

pending 为零，为什么仍有积压？

可能还有尚未投递的消息。查看目标组的 lag；pending 为零只说明 PEL 中当前没有待确认项。

为什么不能用尾部 ID 减去消费 ID？

ID 包含毫秒与序号，间隔不连续，还可能有删除或裁剪。数值差不是条目数量。

多页查询能得到静态完整清单吗？

并发确认、重新投递和清理都会改变观察对象。按 ID 分页避免重复端点，但不会冻结消费者组的状态。

参考：XPENDING；XINFO GROUPS 与 lag；XRANGE 区间读取。