WIUNIX ACADEMY
Kafka consumer lag: diagnose first, rehearse an exact offset reset
Page 2 of 3. Review the earlier steps and prerequisites before continuing.
YOUR 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
LET’S BUILD
Stop every consumer through its owning lifecycle
Use the application’s existing staging stop procedure, including autoscalers, schedulers and standby instances that could rejoin. There is no universal safe kill command. Then run these checks: the group must be inactive with no members before any reset. Recheck immediately before execution; an earlier screenshot does not establish current inactivity. Preserve the consumer configuration and normal restart route.
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 --members
'/opt/kafka/bin/kafka-consumer-groups.sh' --bootstrap-server 'kafka.example.com:9093' --command-config '/etc/kafka/academy-client.properties' --group 'academy_replay' --describe --stateNo member remains or can automatically rejoin during the rehearsal.
LET’S BUILD
Inspect retained start and end positions
Read the selected partition’s current earliest and latest boundaries. Retention keeps moving, so recheck close to execution. A target before the retained start cannot replay expired data. Some reset scenarios adjust an out-of-range request to an available boundary; compare the proposed result rather than assuming the requested number was honored. Timestamp selection is not a business-transaction lookup.
Authorized Kafka administration client
'/opt/kafka/bin/kafka-get-offsets.sh' --bootstrap-server 'kafka.example.com:9093' --command-config '/etc/kafka/academy-client.properties' --topic 'academy_events' --partitions 0 --time -2
'/opt/kafka/bin/kafka-get-offsets.sh' --bootstrap-server 'kafka.example.com:9093' --command-config '/etc/kafka/academy-client.properties' --topic 'academy_events' --partitions 0 --time -1The reviewed target lies within the retained available interval.
LET’S BUILD
Export the original committed position privately
Use a brand-new private directory under an approved writable parent. This exports only the selected topic/partition’s current position and does not execute a reset. Inspect the CSV: it must contain the intended topic, partition and committed numeric offset. Stop if the group has no committed offset for that partition. Do not treat this CSV as a data backup or a rollback of external effects.
Authorized Kafka administration client
test ! -e '/home/academy/kafka-offset-rehearsal-20261028' && test ! -L '/home/academy/kafka-offset-rehearsal-20261028' || exit 1
(umask 077; mkdir -- '/home/academy/kafka-offset-rehearsal-20261028') || exit 1
umask 077
'/opt/kafka/bin/kafka-consumer-groups.sh' --bootstrap-server 'kafka.example.com:9093' --command-config '/etc/kafka/academy-client.properties' --group 'academy_replay' --reset-offsets --topic 'academy_events:0' --to-current --export > '/home/academy/kafka-offset-rehearsal-20261028/before.csv'
cat '/home/academy/kafka-offset-rehearsal-20261028/before.csv'An exact private one-partition before-state CSV exists.
LET’S BUILD
Preview the exact one-partition movement
Dry-run is read-only with respect to committed offsets. Compare group/topic/partition/new offset with the approved plan and retained boundaries. Rewind means duplicate processing may occur after restart; forward movement skips unprocessed records. Neither should be used as a generic cure for lag. The example is a staging rehearsal while no consumer runs.
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' --reset-offsets --topic 'academy_events:0' --to-offset 0 --dry-runOnly the exact approved partition and reviewed target are proposed.
LET’S BUILD
Apply only while the staging group remains inactive
This is the deliberate state-changing step, not an observation command. Recheck inactivity immediately. Execute only after accepting the duplicate/skip consequence for the synthetic staging data. Keep consumers stopped afterwards so the rehearsal can return to the captured position without adding new processing effects. If the command fails or reports a different offset, preserve evidence and diagnose rather than repeating against a moving group.
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 --state
'/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
'/opt/kafka/bin/kafka-consumer-groups.sh' --bootstrap-server 'kafka.example.com:9093' --command-config '/etc/kafka/academy-client.properties' --group 'academy_replay' --reset-offsets --topic 'academy_events:0' --to-offset 0 --execute
'/opt/kafka/bin/kafka-consumer-groups.sh' --bootstrap-server 'kafka.example.com:9093' --command-config '/etc/kafka/academy-client.properties' --group 'academy_replay' --describeCommitted position equals the reviewed target; consumers remain inactive.
LET’S BUILD
Return the offline rehearsal to the captured position
For this rehearsal only, with no consumer restarted and no new effects, preview then execute the captured CSV. If any consumer processed after the reset, stop: offset restoration is not a business rollback and can replay or skip additional work. CSV scope replaces the topic-selection flag. Recheck final offsets against before.csv, then use the application’s owning restart procedure and monitor correctness/freshness as well as lag.
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' --reset-offsets --from-file '/home/academy/kafka-offset-rehearsal-20261028/before.csv' --dry-run
'/opt/kafka/bin/kafka-consumer-groups.sh' --bootstrap-server 'kafka.example.com:9093' --command-config '/etc/kafka/academy-client.properties' --group 'academy_replay' --reset-offsets --from-file '/home/academy/kafka-offset-rehearsal-20261028/before.csv' --execute
'/opt/kafka/bin/kafka-consumer-groups.sh' --bootstrap-server 'kafka.example.com:9093' --command-config '/etc/kafka/academy-client.properties' --group 'academy_replay' --describeThe inactive rehearsal is restored to its recorded committed position before normal restart.