WIUNIX ACADEMY
Kafka consumer lag: diagnose first, rehearse an exact offset reset
Distinguish processing lag from commit cadence, inspect retained boundaries and rehearse one inactive group partition with a captured before-state.
Make this guide yoursYOUR SYSTEM. YOUR STEPS.
Where are you working?
Choose your OS and version. The prerequisites, commands and troubleshooting follow your environment.
USE YOUR OWN VALUES
Configure this tutorial
Set the example values for your environment; related explanations and copy panels update together. Never enter passwords, private keys or tokens. Values stay in this tab and are not sent to the server or share links. Check actual DNS, certificates and network policy before running commands.
Different IP addresses, domains or ports? Open the settings below, change the values and select “Apply to tutorial”, then copy the updated commands.
Set values for my environment9 editable values
THE OUTCOME
What will you have at the end?
Distinguish processing lag from commit cadence, inspect retained boundaries and rehearse one inactive group partition with a captured before-state.
Supported operating systems and versions
Documented paths for Ubuntu, Debian and Red Hat families with preinstalled compatible products/clients. The first step states each branch’s limits. Service commands were not executed during authoring.
Before you begin
- Existing authorized service and protected client authentication; use the isolated fixture scope specified below.
Lag is a position gap, not a repair instruction
Consumer-group lag compares committed position with an available log boundary; it is not wall-clock freshness and is not always a count of business events. Compaction, transactions, control records and offset gaps complicate that interpretation. Resetting offsets moves a read position; it neither accelerates processing nor reverses side effects. This guide first diagnoses a normal consumer group, then rehearses an explicitly approved single-partition change while all consumers remain stopped.
Use a synthetic staging group, not Streams or share groups
Use matching Kafka4.2 administration tools, an existing protected TLS/SASL client config, a dedicated synthetic topic and normal consumer group. Kafka Streams, Connect and share groups have additional state/reset contracts and are excluded. Do not create a cluster, change retention or delete a group to follow this guide. A group whose external effects cannot tolerate duplicates must not be rewound until its idempotency and recovery design are proven.
Select one exact topic, partition and target
The public form selects names and a numeric target offset; credentials remain in the existing client config outside the browser. Values stay in this tab and Apply updates all panels. The target is the next record position to consume, not the last processed record. The example zero is a placeholder; choose an available reviewed boundary. Typed validity does not prove the offset is retained or meaningful.
The existing native reader field supports up to10decimal digits. This bounded staging rehearsal therefore accepts offsets0–9999999999; larger-offset production workflows require the owning separately reviewed CLI procedure, not truncating the number.
LET’S BUILD
Verify the installed tools and the host on which commands run
The OS selector describes an existing Kafka 4.2 administration client on Ubuntu 26.10/26.04, Debian 13/12 or RHEL/Rocky/Alma 9/10. Apache documents the Java compatibility contract, not certification of each distribution: verify a compatible installed runtime (Java 17, 21 or 25) with java -version. /opt/kafka/bin is the selected existing Apache binary distribution, not a promised distro package path. If your managed installation uses a versioned directory, change the public path before proceeding. The protected client properties file must belong to this operator and refer to the existing TLS/SASL setup; no broker service, listener, firewall or Java installation is changed.
These are documented command paths, not executed compatibility tests. Read /etc/os-release and verify the exact product/version before continuing. Existing accounts, approved network access and protected credentials are prerequisites. Do not restart existing services to provision tools, initialize a database, open a firewall port or alter a system Python installation to make this exercise run.
Approved administration client; node-specific checks only on the existing node
cat /etc/os-release
id
java -version
test -x "/opt/kafka/bin/kafka-consumer-groups.sh"
"/opt/kafka/bin/kafka-consumer-groups.sh" --version
test -r "/etc/kafka/academy-client.properties"The OS, tool path and version match the selected procedure; stop before data changes if they do not.
LET’S BUILD
Inspect assignment, committed offsets and group state
Run from the authorized client. Inspect per-partition lag and members, not only a summed dashboard. Repeat during a representative interval with the existing monitoring. If one partition dominates, examine its key skew and record size; adding consumers beyond assigned partitions cannot parallelize that one ordered partition. A rebalancing group and a slow handler require different responses.
Authorized Kafka administration client
'/opt/kafka/bin/kafka-consumer-groups.sh' --bootstrap-server 'kafka.example.com:9093' --command-config '/etc/kafka/academy-client.properties' --group 'academy_replay' --describe
'/opt/kafka/bin/kafka-consumer-groups.sh' --bootstrap-server 'kafka.example.com:9093' --command-config '/etc/kafka/academy-client.properties' --group 'academy_replay' --describe --members --verbose
'/opt/kafka/bin/kafka-consumer-groups.sh' --bootstrap-server 'kafka.example.com:9093' --command-config '/etc/kafka/academy-client.properties' --group 'academy_replay' --describe --state
'/opt/kafka/bin/kafka-topics.sh' --bootstrap-server 'kafka.example.com:9093' --command-config '/etc/kafka/academy-client.properties' --describe --topic 'academy_events'The bottleneck is tied to exact partitions, assignments and group state.
Check rates and poll behavior before resetting
Compare production rate, processing rate, commit cadence, record age and handler duration. A healthy processing stream with delayed commits can show lag that falls in steps. Rebalances can follow long processing relative to max.poll.interval.ms; changing only session timeout does not fix that. More concurrency can overload a downstream database. A target chosen only to make the lag graph zero can silently skip business work.