Troubleshoot a lagging group with the Kafka Troubleshooter

At a glance

Learning objectives

• Feed an incident agent the inputs it needs — group describe, offsets, logs
• Follow a diagnosis, evidence, fix, prevention loop
• Keep destructive shortcuts like offset resets off the table

What you need

• Consumer-group describe output
• Per-partition offsets
• Consumer application logs
• [object Object]

Steps

1. Check lag trend and per-partition distribution. (from agent-kafka-troubleshooter )
2. Check group state history for rebalances. (from agent-kafka-troubleshooter )
3. Identify poison messages from retry counts. (from agent-kafka-troubleshooter )
4. Recommend the least destructive fix. (from agent-kafka-troubleshooter )
5. Expect four outputs — diagnosis, evidence, fix with risk rating, prevention measure. (from agent-kafka-troubleshooter )
6. Hold the guardrails — never resets offsets, read-only against the cluster. (from agent-kafka-troubleshooter )

Check yourself

• The verdict on "lag on partitions 3 and 7 only, others flat" is to re-key the offending key, not scale the fleet — the agent's own worked example.
• The final recommendation includes a risk rating and a prevention measure, and no offset reset was proposed at any step.

Worked example

kafka-consumer-groups --bootstrap-server $B --describe --group $G
kafka-consumer-groups --bootstrap-server $B --describe --group $G --state

- Check lag trend and per-partition distribution.
- Check group state history for rebalances.
- Identify poison messages from retry counts.
- Recommend the least destructive fix.

Outputs: Diagnosis, Evidence, Fix with risk rating, Prevention measure

Guardrails:
- Never resets offsets
- Read-only against the cluster

Sourced from

• Kafka Troubleshooter
• Kafka Consumer Lag Triage

Security scan

Last sweep 2026-10-24: 0 finding(s), 0 marked as examples.

Common gotchas

• The agent never resets offsets — treat any offset-reset suggestion as out of bounds.
• It stays read-only against the cluster; it will not mutate group state.
• Lag on a few partitions only is key skew, not a capacity problem — the fix is re-keying, not fleet scaling.

Production considerations

• Attach consumer-group describe output and application logs to the incident so the diagnosis is evidence-backed.
• File the prevention measure from each diagnosis as a follow-up action so the same lag signature does not recur.

Diagram

kafka troubleshooter
   |
   |- inputs: describe output + offsets + logs
   |
   |- lag trend + per-partition distribution
   |
   |- group state history --> rebalances
   |
   |- retry counts --> poison messages
   |
   |- least destructive fix --> risk rating + prevention
   |
    --> guardrails: read-only, never reset offsets

Registry stats