Redis XLEN 怎样统计 Stream 中的消息数量

Redis Stream 的总条目数可以直接用 XLEN key 查询。它返回的是这个 Stream 当前包含多少条消息，时间复杂度为 O(1)，不会把消息内容全部读回客户端。需要注意，XLEN 只回答“有多少条”，不回答某个消费组已经确认了多少条、还有多少条待处理。

官方文档：https://redis.io/docs/latest/commands/xlen/

排查 Stream 是否积压时，先用 XLEN 看总量，再根据消费组场景查看 pending 或 lag；不要把 XLEN 的结果直接当成消费组滞后。

先分清 Stream 总条目数和消费状态

Stream 的长度属于数据结构本身，消费组状态属于读取进度。一个 Stream 可以被多个消费组读取，每个组的最后投递位置、pending 数量和 lag 都可能不同，因此“Stream 有 1000 条消息”和“某个组还有 1000 条未消费消息”不是同一个结论。

用 XLEN 读取指定 Stream 的长度

最小用法只有一个参数：Stream 的 key。下面的命令先写入两条示例消息，再读取 Stream 长度；命令中的 * 让 Redis 生成消息 ID。

# 写入两条示例消息，* 表示让 Redis 自动生成消息 ID
redis-cli XADD order-events '*' order_id 1001 status created
redis-cli XADD order-events '*' order_id 1002 status paid

# 只读取 Stream 条目数，不读取具体消息内容
redis-cli XLEN order-events

如果两个 XADD 都成功，XLEN order-events 返回整数 2。这个查询是只读操作，适合在排障命令、定时指标采集或后台健康检查中使用。它不会告诉你消息字段，也不会改变消费组游标。

2

在应用代码里也应把这个整数解释为“当前 Stream 的条目数量”。如果业务需要判断消费者是否落后，应把 XLEN 作为总量背景，再查询具体消费组状态。

处理不存在键、空流和删除后的边界

XLEN 返回 0 时，至少有两种可能：key 不存在，或者 key 存在但 Stream 没有条目。Redis 官方文档特别提醒，零长度 Stream 是可能存在的，所以不能仅凭 XLEN 为 0 就断言 key 不存在。

# 先查看 key 是否存在，再确认它的类型
redis-cli EXISTS order-events
redis-cli TYPE order-events

# key 不存在时 XLEN 也返回 0
redis-cli XLEN missing-events

生产排障时可以按下面的解释处理：

• EXISTS 返回 0：通常是 key 不存在，XLEN 的 0 不能说明 Stream 曾经有过消息。
• EXISTS 返回 1 且 TYPE 为 stream：说明 key 是 Stream；长度为 0 时要继续检查是否被删除或裁剪。
• TYPE 不是 stream：不要继续用 XLEN 解释业务数据，应先修正 key 配置或命名冲突。

Stream 中的条目被 XDEL 删除后，Stream 不一定自动消失，因为它可能仍关联消费组。因此“长度为 0”和“key 已经不存在”仍然是两个独立判断。

把长度查询放进生产排障检查

一个简洁的检查顺序是：先确认 key 类型，再读 XLEN；如果系统使用消费组，再读取 XINFO GROUPS。这样能把数据规模、消费组待处理列表和组的 lag 分开记录。

# 先确认目标 key 是 Stream，避免同名 key 类型误导排查
redis-cli TYPE order-events

# 读取 Stream 总条目数，作为总量基线
redis-cli XLEN order-events

# 只有使用消费组时，才继续查看每个组的 pending 和 lag
redis-cli XINFO GROUPS order-events

XINFO GROUPS 返回的 pending 是已经投递但尚未确认的消息数量，lag 表示仍等待投递的条目数量；它们与 XLEN 的总条目数有不同含义。一个组可能已经消费过部分消息，也可能因为确认、删除或起始 ID 设置而呈现不同状态。

如果只是做容量观察，XLEN 已经足够；如果是在定位消费延迟，则至少要同时记录 Stream key、XLEN、消费组名称、pending 和 lag，并保留采集时间。这样后续才能区分“生产端写入增加”和“消费端处理变慢”。

常见问题

XLEN 返回 0 是不是 Redis key 不存在？

不一定。不存在的 key 会返回 0，零长度 Stream 也会返回 0。用 EXISTS 和 TYPE 进一步确认。

XLEN 能不能直接表示消费组积压？

不能。XLEN 是 Stream 总条目数；消费组积压应查看该组的 pending 和 lag，必要时结合消费组的最后投递 ID 判断。

XLEN 查询会不会遍历整个 Stream？

官方命令文档标注 XLEN 的时间复杂度为 O(1)，适合做轻量的总量读取；它仍然不能替代对消费状态的专门查询。

小结：用 XLEN 看 Stream 总条目数，用 EXISTS 与 TYPE 解释零值，用 XINFO GROUPS 看消费组状态。三类信息分开记录，排障结论才不会把数据总量误当成消费延迟。