XINFO-GROUPS(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

💖 XINFO-GROUPS 💖

okay bestie, so this is a page from the Valkey Command Manual (yes, the 3valkey one) and it's all about XINFO GROUPS — the girl whose whole job is telling you who's in the group chat of a stream. let's get into it 🫶

✨ NAME ✨

xinfo-groups — returns a list of the consumer groups of a stream.

like, it literally hands you the roster. that's it. that's the gig. 💅

🌸 SYNOPSIS 🌸

XINFO GROUPS key

🦋 DESCRIPTION 🦋

So this command returns the list of all consumer groups of the stream stored at key. All of them. No hiding, no filtering, no gatekeeping. 👑

By default, only the following info is provided for each of the groups:

  • name: the consumer group's name 🎀
  • consumers: the number of consumers in the group
  • pending: the length of the group's pending entries list (PEL) — which are messages that were delivered but are yet to be acknowledged 😭 (aka the "you said you'd reply but you didn't" pile)
  • last-delivered-id: the ID of the last entry delivered to the group's consumers
  • entries-read: the logical "read counter" of the last entry delivered to the group's consumers
  • lag: the number of entries in the stream that are still waiting to be delivered to the group's consumers, or a NULL when that number can't be determined

🌈 Consumer group lag 🌈

The lag of a given consumer group is the number of entries in the range between the group's entries_read and the stream's entries_added. Put differently — and honestly this is the cleaner way to say it — it's the number of entries that are yet to be delivered to the group's consumers. 💌

The values and trends of this metric are helpful in making scaling decisions about the consumer group. You can address high lag values by adding more consumers to the group, whereas low values may indicate that you can remove consumers from the group to scale it down. it's giving ✨capacity planning✨

Valkey reports the lag of a consumer group by keeping two counters: the number of all entries added to the stream, and the number of logical reads made by the consumer group. The lag is the difference between these two. simple math, main character energy. 🧮

The stream's counter (the entries_added field of the XINFO STREAM command) is incremented by one with every XADD and counts all of the entries added to the stream during its lifetime.

The consumer group's counter, entries_read, is the logical counter of entries the group had read. It is important to note that this counter is only a heuristic rather than an accurate counter, and therefore the use of the term "logical". The counter attempts to reflect the number of entries that the group should have read to get to its current last-delivered-id. The entries_read counter is accurate only in a perfect world 🌍✨, where a consumer group starts at the stream's first entry and processes all of its entries (i.e., no entries deleted before processing). so like... not our world, bestie 💀

There are two special cases in which this mechanism is unable to report the lag:

  1. A consumer group is created or set with an arbitrary last delivered ID (the XGROUP CREATE and XGROUP SETID commands, respectively). An arbitrary ID is any ID that isn't the ID of the stream's first entry, its last entry or the zero ("0-0") ID.
  2. One or more entries between the group's last-delivered-id and the stream's last-generated-id were deleted (with XDEL or a trimming operation).

In both cases, the group's read counter is considered invalid, and the returned value is set to NULL to signal that the lag isn't currently available. 🙈

However — and this is the good news — the lag is only temporarily unavailable. It is restored automatically during regular operation as consumers keep processing messages. Once the consumer group delivers the last message in the stream to its members, it will be set with the correct logical read counter, and tracking its lag can be resumed. she bounced back. iconic. 💅

💜 REPLY 💜

valkey-protocol(7) Array reply: a list of consumer groups. 🎁

⭐ COMPLEXITY ⭐

O(1) — constant time, no cap, she's fast. 🔥

🎀 ACL CATEGORIES 🎀

@read @slow @stream

👑 HISTORY 👑

  • Available since: 5.0.0
  • Changed in 7.0.0: Added the entries-read and lag fields

glow-up timeline fr fr 🌱→🌸

🍓 EXAMPLES 🍓

> XINFO GROUPS mystream
1)  1) "name"
    2) "mygroup"
    3) "consumers"
    4) (integer) 2
    5) "pending"
    6) (integer) 2
    7) "last-delivered-id"
    8) "1638126030001-0"
    9) "entries-read"
   10) (integer) 2
   11) "lag"
   12) (integer) 0
2)  1) "name"
    2) "some-other-group"
    3) "consumers"
    4) (integer) 1
    5) "pending"
    6) (integer) 0
    7) "last-delivered-id"
    8) "1638126028070-0"
    9) "entries-read"
   10) (integer) 1
   11) "lag"
   12) (integer) 1

two groups, both slaying, one with lag of 0 and one with lag of 1 — not me being emotionally invested in a stream's group chat 😭💖

🌈 SEE ALSO 🌈

xack(3valkey), xadd(3valkey), xautoclaim(3valkey), xclaim(3valkey), xdel(3valkey), xgroup(3valkey), xgroup-create(3valkey), xgroup-createconsumer(3valkey), xgroup-delconsumer(3valkey), xgroup-destroy(3valkey), xgroup-help(3valkey), xgroup-setid(3valkey), xinfo(3valkey), xinfo-consumers(3valkey), xinfo-help(3valkey), xinfo-stream(3valkey), xlen(3valkey), xpending(3valkey), xrange(3valkey), xread(3valkey), xreadgroup(3valkey), xrevrange(3valkey), xsetid(3valkey), xtrim(3valkey)

and that's the whole page bestie, we ate and left no crumbs 🫶✨

version 9.0.0 · dated 2025-10-21 · XINFO-GROUPS(3valkey) — mwah, go read your streams, ily 💖🌸🦋
📦 where this page comes from