klag – Công cụ CLI giúp phân tích nguyên nhân tiêu thụ Kafka bị trễ

klag – Công cụ CLI giúp phân tích nguyên nhân tiêu thụ Kafka bị trễ

Kafka consumer lag là một chỉ số quan trọng phản ánh việc hệ thống tiêu thụ dữ liệu có bị chậm lại hay không. Thông thường, các kỹ sư hay phải mở dashboard Grafana hoặc công cụ giám sát, xem offset queue và cố gắng đoán nguyên nhân: liệu producer có gửi quá nhiều hay không, có xảy ra rebalance hay không, hoặc tiến trình consumer có thực sự còn hoạt động?

klag là một công cụ dòng lệnh (CLI) được phát triển nhằm loại bỏ những suy đoán này. Bằng cách kết nối trực tiếp với Kafka broker, klag chụp nhanh lượng lag trên từng phân vùng, lấy mẫu tốc độ sản xuất và tiêu thụ, và tự động chạy các bộ detector để xác định nguyên nhân gây lag – tất cả đều hiển thị ngay trên terminal của bạn.

Cài đặt và sử dụng cơ bản

Bạn có thể cài đặt klag dễ dàng thông qua npm:

npm install -g @closeup1202/klag

Một số cách sử dụng phổ biến:

• Phân tích một lần:

  klag -b localhost:9092 -g my-consumer-group
  

• Chế độ theo dõi liên tục, tự cập nhật mỗi 5 giây:

  klag -b localhost:9092 -g my-consumer-group --watch
  

• Nếu không truyền nhóm tiêu thụ, klag sẽ cho phép bạn chọn nhóm từ danh sách đang hoạt động:

  klag -b localhost:9092
  

Những trạng thái lag mà klag phát hiện

Sau khi thu thập dữ liệu, klag sẽ chạy đồng thời đến 5 bộ detector để phân tích:

Bộ detector	Phát hiện được
PRODUCER_BURST	Tốc độ sản xuất nhanh hơn gấp 2 lần tiêu thụ, consumer không bắt kịp
SLOW_CONSUMER	Consumer gần như ngừng hoạt động, tốc độ sản xuất vẫn bình thường
OFFSET_NOT_MOVING	Offset không thay đổi dù dữ liệu vẫn được sản xuất – có thể bị deadlock xử lý
REBALANCING	Nhóm consumer đang trong quá trình rebalance, tạm dừng tiêu thụ
HOT_PARTITION	Một phân vùng chiếm tỷ lệ lag quá lớn so với tổng lag

Mỗi kết quả đều đi kèm mô tả hiện trạng quan sát và gợi ý biện pháp khắc phục, ví dụ tăng số lượng consumer hoặc tăng phân vùng.

Ví dụ kết quả đầu ra

Ở ví dụ phân tích nhóm consumer “my-consumer-group”:

⚡ klag  v0.5.0

🔍 Consumer Group: my-consumer-group
   Broker:         localhost:9092
   Collected At:   2026-04-06 14:32:01 (Asia/Seoul)

   Group Status : 🚨 CRITICAL   Total Lag : 80,500   Drain : 58m15s

┌──────────┬─────────┬──────────────┬─────────────┬───────┬─────────┬─────────┬─────────────┬─────────────┐
│ Topic    │ Partition│ Committed Off│ Log-End Off │ Lag   │ Status  │ Drain   │ Produce Rate│ Consume Rate│
├──────────┼─────────┼──────────────┼─────────────┼───────┼─────────┼─────────┼─────────────┼─────────────┤
│ orders   │ 0       │ 1,200,000    │ 1,242,000   │ 42,000│ 🔴 HIGH │ 58m20s  │ 120.0 msg/s │ 12.0 msg/s  │
│          │ 1       │ 1,198,500    │ 1,237,000   │ 38,500│ 🔴 HIGH │ 58m10s  │ 115.0 msg/s │ 11.0 msg/s  │
└──────────┴─────────┴──────────────┴─────────────┴───────┴─────────┴─────────┴─────────────┴─────────────┘

🔎 Root Cause Analysis

[PRODUCER_BURST] orders
→ produce rate 235.0 msg/s vs consume rate 23.0 msg/s (10.2x difference) — consumer is falling behind ingestion rate
→ Suggestion: Consider increasing consumer instances or partition count

Hỗ trợ bảo mật SSL và SASL

klag cũng hỗ trợ chạy trên các môi trường Kafka sản xuất có cấu hình bảo mật:

• SASL/SCRAM:

  klag -b broker:9092 -g my-group \
  --sasl-mechanism scram-sha-256 \
  --sasl-username user \
  --sasl-password pass
  

• Mutual TLS:

  klag -b broker:9092 -g my-group \
  --ssl-ca ./ca.pem \
  --ssl-cert ./client.pem \
  --ssl-key ./client.key
  

Người dùng cũng có thể đặt cấu hình mặc định cho klag ở file .klagrc để giảm thiểu phải nhập lại nhiều tùy chọn lặp lại.

Định dạng JSON cho tích hợp hệ thống

Để tích hợp vào hệ thống giám sát hoặc tự động hóa, bạn có thể xuất kết quả dạng JSON:

klag -b localhost:9092 -g my-group --json

Cách klag hoạt động

Quy trình phân tích gồm 4 bước chính:

1. Thu thập lag: Kết nối Kafka broker và lấy committed offset cùng log-end offset từng phân vùng.
2. Lấy mẫu tốc độ: Chờ một khoảng thời gian (mặc định 5 giây), lấy offset lần 2 để tính tốc độ sản xuất và tiêu thụ.
3. Phân tích: Chạy các bộ detector độc lập trên snapshot dữ liệu.
4. Báo cáo: Hiển thị bảng màu với mức độ nghiêm trọng (OK, WARN, HIGH) và ước tính thời gian khắc phục.

Mức độ nghiêm trọng dựa trên “time-to-drain” – thời gian cần để consumer bắt kịp lượng backlog dữ liệu:

Mức độ	Thời gian drain
OK	Dưới 60 giây
WARN	1-5 phút
HIGH	Trên 5 phút hoặc tiêu thụ bằng 0

Các detector được thiết kế để loại trừ lẫn nhau, tránh gây nhiễu trong báo cáo.

Lộ trình và phát triển tương lai

Những tính năng dự kiến bổ sung:

• Chế độ cảnh báo khi lag vượt ngưỡng (exit code không bằng 0)
• Phân tích root cause chi tiết theo từng phân vùng
• Hỗ trợ xuất số liệu cho Prometheus

Tham khảo

• npm: npm install -g @closeup1202/klag
• GitHub: https://github.com/closeup1202/klag

Nếu bạn là kỹ sư hoặc quản trị viên vận hành Kafka và thường xuyên phải quan sát các dashboard lag, klag là công cụ đáng thử để giảm thời gian xác định sự cố, nhằm tối ưu hiệu suất hệ thống.