Redis XINFO STREAM FULL 怎样查看 Stream 的完整明细

Redis Stream 出现积压、消费组状态不清楚时，XINFO STREAM 是查看结构信息的入口。只想看规模和首尾状态时使用摘要命令；需要看到条目、消费组、消费者和待确认消息（PEL）时，再加上 FULL，并用 COUNT 控制读取量。

官方地址：https://redis.io/docs/latest/commands/xinfo-stream/

最稳妥的用法是先执行 XINFO STREAM stream_key 看摘要，再执行 XINFO STREAM stream_key FULL COUNT 10 查看有限明细。FULL 默认只展开 10 条相关条目；COUNT 0 表示不限制数量，数据量大时不要直接使用。

一、XINFO STREAM 摘要先看哪些字段

不加 FULL 时，命令返回 Stream 的概览信息，适合先判断对象是否存在、长度是否异常、首尾条目是什么，以及是否有消费组。常见字段包括 length、first-entry、last-entry、groups、entries-added 和 last-generated-id。

# 先看 Stream 的摘要，确认规模和首尾条目
redis-cli XINFO STREAM orders:events

# 只查看长度，适合配合人工记录做快速判断
redis-cli XLEN orders:events

length 表示当前 Stream 中的条目数，entries-added 是生命周期内加入过的条目计数，两者并不等价。Stream 被裁剪或删除过条目后，生命周期计数可能仍然大于当前长度；排查时不要把它们当成同一个指标。

二、FULL 和 COUNT 怎样组合读取明细

FULL 会把输出扩展为更详细的 Stream 状态，包括条目列表以及消费组、消费者和 pending 信息。语法可以写成：

# 读取默认数量的扩展明细，适合先确认返回结构
redis-cli XINFO STREAM orders:events FULL

# 只读取前 20 条相关明细，限制诊断输出规模
redis-cli XINFO STREAM orders:events FULL COUNT 20

# COUNT 0 表示不限制条目数量，只适合小 Stream 或离线分析
redis-cli XINFO STREAM orders:events FULL COUNT 0

在 FULL 模式下，COUNT 的默认值是 10；显式设置一个小的正整数，可以先获得可读的样本。COUNT 0 不是“返回零条”，而是取消数量上限，Stream 很大时可能带来很长的响应和额外处理成本。

这里的 COUNT 主要约束返回的 Stream 条目以及相关 PEL 明细数量，不会把命令变成分页游标。需要持续观察时，应由调用方分次取样并保存自己的诊断时间，而不是把一次 FULL 响应当成消息消费流程。

三、FULL 返回的 groups、consumers 和 pending 怎么看

FULL 的层次可以按“Stream → 消费组 → 消费者 → pending”来读。每个消费组包含最近投递位置、逻辑读取计数和积压相关信息；每个消费者包含名称、最近交互时间及自己的 PEL 数量；每条 pending 明细通常包含消息 ID、当前消费者、投递时间和投递次数。

# 下面是字段关系的阅读顺序，不是伪造的运行输出
Stream
└── groups
    └── group: orders-workers
        ├── last-delivered-id
        ├── lag / pel-count
        ├── consumers
        │   └── consumer: worker-1
        │       ├── seen-time / active-time
        │       └── pel-count
        └── pending
            └── message-id, owner, delivery-time, delivery-count

看到 pel-count 增大时，只能说明已投递但尚未确认的消息数量增加；它不直接说明消费者已经宕机，也不等于整个 Stream 的长度。lag 是尚待投递的逻辑数量，和已经进入 PEL 的 pending 数量是两个观察角度。

四、用一次受控诊断区分“积压”与“结构状态”

如果目标是回答“Stream 有没有消息、消费组有几个、最后投递到哪里”，先看摘要；如果还要定位是哪一个消费组或消费者持有 pending，再用较小 COUNT 的 FULL。下面的命令组合只读取状态，不会确认、删除、转移或消费消息：

# 第一步：记录当前 Stream 的总长度和消费组数量
redis-cli XINFO STREAM orders:events

# 第二步：只展开少量条目和 PEL，避免一次响应过大
redis-cli XINFO STREAM orders:events FULL COUNT 10

# 第三步：单独查看消费组摘要，便于和 FULL 结果对照
redis-cli XINFO GROUPS orders:events

对照时可以把结果分成三类：当前长度回答 Stream 里还有多少条目；消费组状态回答投递进度与待确认数量；条目明细回答具体 ID 和字段值。这样可以避免看到 pending 后直接把诊断命令误当成恢复命令。

五、客户端解析时要注意 RESP 和大响应

Redis 客户端可能把摘要结果呈现为列表或映射，具体取决于 RESP 协议和客户端库的解码方式；不要仅凭打印格式判断字段语义。对 FULL 结果，建议在客户端适配层明确处理“顶层字段、entries、groups、consumers、pending”这些层次，避免把嵌套数组按简单键值对强行配对。

# 用 redis-py 发送受控诊断请求；不把 FULL COUNT 0 用于大 Stream
import redis

client = redis.Redis(host="127.0.0.1", port=6379, decode_responses=True)

# 先读摘要，避免一开始就拉取完整条目和 PEL
summary = client.execute_command("XINFO", "STREAM", "orders:events")

# 需要明细时限制返回规模，再交给适配层解析嵌套结构
details = client.execute_command(
    "XINFO", "STREAM", "orders:events", "FULL", "COUNT", 10
)
print(summary)
print(details)

示例中的地址、键名和数量只是命令参数示意，并不代表某个线上实例的真实结果。生产诊断前要结合 Stream 大小、客户端超时和日志采样策略设定 COUNT；数据量确实很小，或已经在离线环境中处理时，才考虑 COUNT 0。

六、常见问题

1. XINFO STREAM 不加 FULL 能看到 pending 明细吗？

不能。不加 FULL 主要得到 Stream 摘要；要看消费组、消费者和 pending 的扩展状态，需要使用 FULL，或者分别使用 XINFO GROUPS、XINFO CONSUMERS、XPENDING 等专门命令。

2. FULL COUNT 10 是只返回 Stream 的前十条消息吗？

它是对 FULL 明细规模的限制，不应理解为一个可用于业务消费的分页接口。业务读取仍应使用 XREAD 或 XREADGROUP，并根据消费语义处理确认。

3. COUNT 0 为什么可能让响应突然变大？

COUNT 0 表示不限制返回数量，会把所有可返回的条目和相关明细纳入响应。Stream 较大时，响应体、客户端解码时间和内存占用都会增加。

4. pending 数量大是否说明 Stream 已经没有新消息？

不一定。pending 表示已经投递但尚未确认的消息；Stream 仍可能有尚未投递的新条目。应同时对照 Stream 摘要、消费组的投递位置和 lag 等字段。

总结

XINFO STREAM 适合先看 Stream 摘要，FULL 用于展开条目和消费组层次，COUNT 用于控制诊断响应范围。实际排查时先摘要、后小 COUNT 的 FULL，最后再按 groups、consumers、pending 分层解释；不要把它当作消费、确认或消息恢复命令。