--- title: "Diagnose consumer lag with kafka-consumer-groups --describe" description: "One of two consumers stops polling. Spot its rising LAG in kafka-consumer-groups, name it with --members and keep the Kafka lag table on screen with watch." url: https://monedula.dev/kafka-simulator/scenarios/diagnose-lag/ --- # Diagnose consumer lag with kafka-consumer-groups --describe Scenario 13.1.2 · Diagnose lag before opening the inspector. Terminal ops · Intermediate · about 3 min · Apache Kafka 4.3. One stalled consumer, one climbing LAG column: find it with kafka-consumer-groups, name the member with --members, and keep the table on screen with watch. Run it: https://monedula.dev/kafka-simulator/playground/?scenario=13.1.2 ## What you start with This scenario is played from the terminal (Ctrl and the backtick key). A two-partition topic, a group of two consumers, and one of them stops polling while the producer keeps appending. The lag table is the first thing an on-call engineer looks at, and it is enough to find the bad member without opening the inspector at all. ## Step by step 1. **A group of two, nothing produced yet** (t+0.000s): Open the terminal with Ctrl and the backtick key (on a phone, the "..." menu). Nothing has been produced yet, so nobody can be behind: `kafka-consumer-groups --list` shows the one group, and `kafka-consumer-groups --describe --group g1` already prints a row per partition. Neither row has a committed offset yet, so its LAG reads "-", not 0: in this table "nothing committed" and "nothing to catch up on" are different answers. [Open at this step](https://monedula.dev/kafka-simulator/playground/?scenario=13.1.2&t=0) 2. **Six records in, both members keeping up** (t+3.200s): Both members are polling. `kafka-consumer-groups --describe --group g1` gives you one row per partition, each with a real CONSUMER-ID and a LAG at or near zero. A lone 1 there is not a problem: LAG is measured against the COMMITTED offset and auto-commit lands on the NEXT poll, so a record that has just been read still counts for one more tick. [Open at this step](https://monedula.dev/kafka-simulator/playground/?scenario=13.1.2&t=1) 3. **One member stopped polling** (t+5.200s): c2 got stuck in record processing while the producer kept appending. `kafka-consumer-groups --describe --group g1` now shows a "-" where one partition's consumer used to be, and that row's LAG pulling away from its sibling. Keep it on screen with `watch -n 1 kafka-consumer-groups --describe --group g1`: you get a dim header line carrying the command and the SIM clock, and the table under it rewritten in place as LAG climbs. The `-n 1` only decorates that header, so there is no wall clock to wait for. The re-render rides the displayed frames, so pausing the scenario freezes the header and the table with it. [Open at this step](https://monedula.dev/kafka-simulator/playground/?scenario=13.1.2&t=2) 4. **Which member is it?** (t+6.800s): The gap has widened. `kafka-consumer-groups --describe --group g1` shows it, but the lag table names the PARTITION, not the member, so `kafka-consumer-groups --describe --group g1 --members --verbose` is the other half of the diagnosis: its ASSIGNMENT column says who owns that partition. `kafka-consumer-groups --describe --group g1 --state` shows the group is still Stable, which is why nothing rebalanced under you. [Open at this step](https://monedula.dev/kafka-simulator/playground/?scenario=13.1.2&t=3) 5. **Caught up again** (t+9.400s): c2 started polling again and worked through its backlog a batch per poll. `kafka-consumer-groups --describe --group g1` has both partitions level, committed offset equal to log end offset. `kafka-get-offsets --topic orders` reads those same log ends straight off the brokers, without going through the group at all. [Open at this step](https://monedula.dev/kafka-simulator/playground/?scenario=13.1.2&t=4) ## The takeaway LAG is per partition, and it is measured against the COMMITTED offset. A stalled member still owns its partition but reads nothing, so the table shows a "-" consumer with its lag climbing while its sibling stays level - that one row is the diagnosis. Read the "-" carefully, though: this simulator stops crediting a member that is not reading, whereas real kafka-consumer-groups keeps printing a stuck-but-heartbeating member's CONSUMER-ID and prints "-" when a partition is UNOWNED. The climbing LAG next to a level sibling is the signal in both. Because the commit lands on the NEXT poll, a member that has just drained its partition can still read LAG 1 for one more poll. watch keeps the table on screen and re-renders on every displayed frame, so pausing the scenario freezes it too. ## Further reading - [Apache Kafka documentation](https://kafka.apache.org/43/operations/basic-kafka-operations/) ## Troubleshooting - [Kafka consumer lag keeps growing: causes and fixes](https://monedula.dev/kafka-simulator/troubleshooting/consumer-lag-keeps-growing/)