@closeup1202/klag 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 closeup1202
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# klag
+
+> Know **why** your Kafka consumer lag is growing — in 5 seconds from the terminal
+
+[![npm version](https://badge.fury.io/js/klag.svg)](https://www.npmjs.com/package/klag)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Compared to existing tools
+
+| | Burrow | Kafka UI | **klag** |
+|--|--------|----------|---------------|
+| Lag measurement | ✅ | ✅ | ✅ |
+| Root cause detection | ❌ | ❌ | ✅ |
+| CLI (npx) | ❌ | ❌ | ✅ |
+| Requires separate server | ✅ | ✅ | ❌ |
+
+## Run without installation
+```bash
+npx @closeup1202/klag --broker localhost:9092 --group my-service
+```
+
+## Output example
+```
+⚡ klag  v0.1.0
+
+🔍 Consumer Group: my-service
+   Broker:         localhost:9092
+   Collected At:   2026-03-26 17:27:27 (Asia/Seoul)
+
+   Group Status : ⚠️  WARNING   Total Lag : 1,234
+
+┌────────┬───────────┬──────────────────┬────────────────┬───────┬─────────┬──────────────┬──────────────┐
+│ Topic  │ Partition │ Committed Offset │ Log-End Offset │  Lag  │ Status  │ Produce Rate │ Consume Rate │
+├────────┼───────────┼──────────────────┼────────────────┼───────┼─────────┼──────────────┼──────────────┤
+│ orders │         0 │            8,796 │         10,000 │ 1,204 │ 🔴 HIGH │  40.0 msg/s  │   0.0 msg/s  │
+│ orders │         1 │            9,988 │         10,000 │    12 │ 🟢 OK   │   0.0 msg/s  │   0.0 msg/s  │
+│ orders │         2 │            9,982 │         10,000 │    18 │ 🟢 OK   │   0.0 msg/s  │   0.0 msg/s  │
+└────────┴───────────┴──────────────────┴────────────────┴───────┴─────────┴──────────────┴──────────────┘
+
+🔎 Root Cause Analysis
+   [PRODUCER_BURST] orders
+   → produce rate 40.0 msg/s vs consume rate 0.0 msg/s (∞x difference)
+   → Suggestion: consider increasing consumer instances or partition count
+
+   [HOT_PARTITION] orders
+   → partition-0 holds 98% of lag (1,204 / 1,234) — skewed to 1 of 3 partitions
+   → Suggestion: review partition key distribution strategy or consider increasing partition count
+```
+
+## Installation
+```bash
+npm install -g @closeup1202/klag
+```
+
+## Usage
+```bash
+# Basic usage
+klag --broker localhost:9092 --group my-service
+
+# Fast mode without rate sampling
+klag --broker localhost:9092 --group my-service --no-rate
+
+# Watch mode (auto-refresh every N seconds)
+klag --broker localhost:9092 --group my-service --watch
+klag --broker localhost:9092 --group my-service --watch --interval 3000
+
+# JSON output (CI/pipeline integration)
+klag --broker localhost:9092 --group my-service --json
+```
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-b, --broker <host:port>` | Kafka broker address | `localhost:9092` |
+| `-g, --group <groupId>` | Consumer group ID | (required) |
+| `-i, --interval <ms>` | Rate sampling interval | `5000` |
+| `-t, --timeout <ms>` | Connection timeout | `5000` |
+| `-w, --watch` | Watch mode | `false` |
+| `--no-rate` | Skip rate sampling | `false` |
+| `--json` | JSON output | `false` |
+
+## Detectable root causes
+
+### `[HOT_PARTITION]`
+When 80% or more of total lag is concentrated on a single partition.
+Occurs when producer key distribution is uneven (key skew).
+
+### `[PRODUCER_BURST]`
+When produce rate is at least 2x the consume rate (and the consumer is still running).
+Occurs when traffic spikes and the consumer cannot keep up.
+
+### `[SLOW_CONSUMER]`
+When the produce rate is active but the consume rate has dropped to near zero.
+Occurs when the consumer process has stalled, crashed, or is blocked (e.g., long GC pause).
+
+### `[REBALANCING]`
+When the consumer group is in `PreparingRebalance` or `CompletingRebalance` state.
+All consumption pauses during rebalancing, which can cause a temporary lag spike.
+
+## Requirements
+
+- Node.js >= 18
+- Kafka >= 2.0
+
+## Roadmap
+
+- [x] v0.1.0 — lag collection, hot partition, producer burst, slow consumer, rebalancing detection, watch mode with lag trend (▲▼)
+- [ ] v0.2.0 — multi-group monitoring
+- [ ] v0.3.0 — Slack alerts, Prometheus export
+
+## License
+
+MIT © [closeup1202](https://github.com/closeup1202/klag)

package/dist/cli/index.js

@@ -0,0 +1,738 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import chalk3 from "chalk";
+import { Command } from "commander";
+
+// src/analyzer/burstDetector.ts
+var BURST_RATIO_THRESHOLD = 2;
+var MIN_PRODUCE_RATE = 1;
+var STALLED_CONSUME_RATE = 0.1;
+function detectProducerBurst(snapshot, rateSnapshot) {
+  const { partitions: ratePartitions } = rateSnapshot;
+  if (ratePartitions.length === 0) return [];
+  const topicRateMap = /* @__PURE__ */ new Map();
+  for (const p of ratePartitions) {
+    let entry = topicRateMap.get(p.topic);
+    if (!entry) {
+      entry = { totalProduce: 0, totalConsume: 0 };
+      topicRateMap.set(p.topic, entry);
+    }
+    entry.totalProduce += p.produceRate;
+    entry.totalConsume += p.consumeRate;
+  }
+  const results = [];
+  for (const [topic, rates] of topicRateMap) {
+    const { totalProduce, totalConsume } = rates;
+    if (totalProduce < MIN_PRODUCE_RATE) continue;
+    if (totalConsume < STALLED_CONSUME_RATE) continue;
+    if (totalProduce / totalConsume < BURST_RATIO_THRESHOLD) continue;
+    const topicLag = snapshot.partitions.filter((p) => p.topic === topic).reduce((sum, p) => sum + p.lag, 0n);
+    if (topicLag === 0n) continue;
+    results.push({
+      type: "PRODUCER_BURST",
+      topic,
+      description: `produce rate ${totalProduce.toFixed(1)} msg/s vs consume rate ${totalConsume.toFixed(1)} msg/s (${(totalProduce / totalConsume).toFixed(1)}x difference) \u2014 consumer is falling behind ingestion rate`,
+      suggestion: "Consider increasing consumer instances or partition count"
+    });
+  }
+  return results;
+}
+
+// src/analyzer/hotPartitionDetector.ts
+var HOT_PARTITION_THRESHOLD = 0.8;
+var MIN_TOPIC_LAG = 10n;
+function detectHotPartition(snapshot) {
+  const { partitions } = snapshot;
+  if (partitions.length === 0) return [];
+  const topicMap = /* @__PURE__ */ new Map();
+  for (const p of partitions) {
+    if (!topicMap.has(p.topic)) topicMap.set(p.topic, []);
+    topicMap.get(p.topic)?.push(p);
+  }
+  const results = [];
+  for (const [topic, topicPartitions] of topicMap) {
+    if (topicPartitions.length <= 1) continue;
+    const topicTotalLag = topicPartitions.reduce((sum, p) => sum + p.lag, 0n);
+    if (topicTotalLag === 0n) continue;
+    if (topicTotalLag < MIN_TOPIC_LAG) continue;
+    const details = topicPartitions.filter((p) => p.lag > 0n).map((p) => ({
+      partition: p.partition,
+      lag: p.lag,
+      ratio: Number(p.lag) / Number(topicTotalLag)
+    })).sort((a, b) => b.ratio - a.ratio);
+    const top = details[0];
+    if (!top || top.ratio < HOT_PARTITION_THRESHOLD) continue;
+    const ratioPercent = Math.round(top.ratio * 100);
+    const totalPartitionCount = topicPartitions.length;
+    results.push({
+      type: "HOT_PARTITION",
+      topic,
+      description: `partition-${top.partition} holds ${ratioPercent}% of lag (${top.lag.toLocaleString()} / ${topicTotalLag.toLocaleString()}) \u2014 1 of ${totalPartitionCount} partitions is skewed`,
+      suggestion: "Consider reviewing the partition key distribution strategy or increasing the partition count",
+      details
+    });
+  }
+  return results;
+}
+
+// src/analyzer/rebalancingDetector.ts
+var REBALANCING_STATES = ["PreparingRebalance", "CompletingRebalance"];
+function detectRebalancing(snapshot) {
+  const { groupState, totalLag } = snapshot;
+  if (!REBALANCING_STATES.includes(groupState)) return null;
+  if (totalLag === 0n) return null;
+  const isPreparing = groupState === "PreparingRebalance";
+  return {
+    type: "REBALANCING",
+    topic: "*",
+    description: `consumer group is currently in ${groupState} state \u2014 all consumption is paused during rebalancing`,
+    suggestion: isPreparing ? "A new consumer joined or left the group. Lag may spike temporarily \u2014 monitor if it recovers after rebalancing completes" : "Rebalancing is completing. Lag should recover shortly once partition assignment is finalized"
+  };
+}
+
+// src/analyzer/slowConsumerDetector.ts
+var MIN_PRODUCE_RATE2 = 1;
+var STALLED_CONSUME_RATE2 = 0.1;
+function detectSlowConsumer(snapshot, rateSnapshot) {
+  const { partitions: ratePartitions } = rateSnapshot;
+  if (ratePartitions.length === 0) return [];
+  const topicRateMap = /* @__PURE__ */ new Map();
+  for (const p of ratePartitions) {
+    let entry = topicRateMap.get(p.topic);
+    if (!entry) {
+      entry = { totalProduce: 0, totalConsume: 0 };
+      topicRateMap.set(p.topic, entry);
+    }
+    entry.totalProduce += p.produceRate;
+    entry.totalConsume += p.consumeRate;
+  }
+  const results = [];
+  for (const [topic, rates] of topicRateMap) {
+    const { totalProduce, totalConsume } = rates;
+    if (totalProduce < MIN_PRODUCE_RATE2) continue;
+    if (totalConsume >= STALLED_CONSUME_RATE2) continue;
+    const topicLag = snapshot.partitions.filter((p) => p.topic === topic).reduce((sum, p) => sum + p.lag, 0n);
+    if (topicLag === 0n) continue;
+    results.push({
+      type: "SLOW_CONSUMER",
+      topic,
+      description: `consumer has stalled \u2014 produce rate ${totalProduce.toFixed(1)} msg/s but consume rate is near 0 \u2014 messages are accumulating with no consumption`,
+      suggestion: "Check if consumer process is alive, look for errors in consumer logs, or check for long GC pauses"
+    });
+  }
+  return results;
+}
+
+// src/analyzer/index.ts
+function analyze(snapshot, rateSnapshot) {
+  const results = [];
+  const rebalancing = detectRebalancing(snapshot);
+  if (rebalancing) results.push(rebalancing);
+  if (rateSnapshot) {
+    results.push(...detectProducerBurst(snapshot, rateSnapshot));
+    results.push(...detectSlowConsumer(snapshot, rateSnapshot));
+  }
+  results.push(...detectHotPartition(snapshot));
+  return results;
+}
+
+// src/collector/lagCollector.ts
+import { AssignerProtocol, Kafka, logLevel } from "kafkajs";
+async function collectLag(options) {
+  const kafka = new Kafka({
+    clientId: "klag",
+    brokers: [options.broker],
+    logLevel: logLevel.NOTHING,
+    // Hide kafkajs internal logs in CLI
+    requestTimeout: options.timeoutMs ?? 5e3,
+    connectionTimeout: options.timeoutMs ?? 3e3,
+    retry: {
+      retries: 1
+      // Added — only 1 retry (default is 5)
+    }
+  });
+  const admin = kafka.admin();
+  try {
+    await admin.connect();
+    const groupDescription = await admin.describeGroups([options.groupId]);
+    const group = groupDescription.groups[0];
+    if (!group) {
+      throw new Error(`Consumer group "${options.groupId}" not found`);
+    }
+    if (group.state === "Dead") {
+      throw new Error(`Consumer group "${options.groupId}" is in Dead state`);
+    }
+    const topicPartitionMap = /* @__PURE__ */ new Map();
+    for (const member of group.members) {
+      if (!member.memberAssignment) continue;
+      try {
+        const decoded = AssignerProtocol.MemberAssignment.decode(
+          member.memberAssignment
+        );
+        for (const [topic, partitions2] of Object.entries(decoded?.assignment)) {
+          if (!topicPartitionMap.has(topic)) {
+            topicPartitionMap.set(topic, /* @__PURE__ */ new Set());
+          }
+          for (const p of partitions2) {
+            topicPartitionMap.get(topic)?.add(p);
+          }
+        }
+      } catch {
+      }
+    }
+    const topicNames = [...topicPartitionMap.keys()];
+    const committedOffsets = await admin.fetchOffsets({
+      groupId: options.groupId,
+      topics: topicNames.length > 0 ? topicNames : void 0
+    });
+    for (const topicOffset of committedOffsets) {
+      if (!topicPartitionMap.has(topicOffset.topic)) {
+        topicPartitionMap.set(topicOffset.topic, /* @__PURE__ */ new Set());
+      }
+      for (const p of topicOffset.partitions) {
+        topicPartitionMap.get(topicOffset.topic)?.add(p.partition);
+      }
+    }
+    const topicList = [...topicPartitionMap.keys()];
+    const logEndEntries = await Promise.all(
+      topicList.map(async (topic) => {
+        const offsets = await admin.fetchTopicOffsets(topic);
+        const partitionMap = /* @__PURE__ */ new Map();
+        for (const p of offsets) {
+          partitionMap.set(p.partition, BigInt(p.offset));
+        }
+        return [topic, partitionMap];
+      })
+    );
+    const logEndOffsetMap = new Map(logEndEntries);
+    const committedOffsetMap = /* @__PURE__ */ new Map();
+    for (const topicOffset of committedOffsets) {
+      const partitionMap = /* @__PURE__ */ new Map();
+      for (const p of topicOffset.partitions) {
+        const offset = p.offset === "-1" ? 0n : BigInt(p.offset);
+        partitionMap.set(p.partition, offset);
+      }
+      committedOffsetMap.set(topicOffset.topic, partitionMap);
+    }
+    const partitions = [];
+    for (const [topic, partitionSet] of topicPartitionMap) {
+      const logEndMap = logEndOffsetMap.get(topic) ?? /* @__PURE__ */ new Map();
+      const commitMap = committedOffsetMap.get(topic) ?? /* @__PURE__ */ new Map();
+      for (const partition of partitionSet) {
+        const logEndOffset = logEndMap.get(partition) ?? 0n;
+        const committedOffset = commitMap.get(partition) ?? 0n;
+        const lag = logEndOffset > committedOffset ? logEndOffset - committedOffset : 0n;
+        partitions.push({
+          topic,
+          partition,
+          logEndOffset,
+          committedOffset,
+          lag
+        });
+      }
+    }
+    partitions.sort(
+      (a, b) => a.topic.localeCompare(b.topic) || a.partition - b.partition
+    );
+    const totalLag = partitions.reduce((sum, p) => sum + p.lag, 0n);
+    return {
+      groupId: options.groupId,
+      broker: options.broker,
+      collectedAt: /* @__PURE__ */ new Date(),
+      partitions,
+      totalLag,
+      groupState: group.state
+    };
+  } finally {
+    await admin.disconnect();
+  }
+}
+
+// src/collector/rateCollector.ts
+import { Kafka as Kafka2, logLevel as logLevel2 } from "kafkajs";
+async function collectRate(options, knownTopics) {
+  const intervalMs = options.intervalMs ?? 5e3;
+  const intervalSec = intervalMs / 1e3;
+  const kafka = new Kafka2({
+    clientId: "klag-rate",
+    brokers: [options.broker],
+    logLevel: logLevel2.NOTHING,
+    requestTimeout: options.timeoutMs ?? 5e3,
+    connectionTimeout: options.timeoutMs ?? 3e3,
+    retry: {
+      retries: 1
+      // Added — only 1 retry (default is 5)
+    }
+  });
+  const admin = kafka.admin();
+  try {
+    await admin.connect();
+    const committedRaw = await admin.fetchOffsets(
+      knownTopics && knownTopics.length > 0 ? { groupId: options.groupId, topics: knownTopics } : { groupId: options.groupId }
+    );
+    const topics = committedRaw.map((t) => t.topic);
+    if (topics.length === 0) {
+      return { intervalMs, partitions: [] };
+    }
+    const logEnd1 = await fetchLogEndOffsets(admin, topics);
+    const committed1 = buildCommittedMap(committedRaw);
+    await sleep(intervalMs);
+    const committedRaw2 = await admin.fetchOffsets({
+      groupId: options.groupId,
+      topics
+    });
+    const logEnd2 = await fetchLogEndOffsets(admin, topics);
+    const committed2 = buildCommittedMap(committedRaw2);
+    const partitions = [];
+    for (const topic of topics) {
+      const end1 = logEnd1.get(topic) ?? /* @__PURE__ */ new Map();
+      const end2 = logEnd2.get(topic) ?? /* @__PURE__ */ new Map();
+      const com1 = committed1.get(topic) ?? /* @__PURE__ */ new Map();
+      const com2 = committed2.get(topic) ?? /* @__PURE__ */ new Map();
+      const allPartitions = /* @__PURE__ */ new Set([...end1.keys(), ...end2.keys()]);
+      for (const partition of allPartitions) {
+        const logEndDiff = (end2.get(partition) ?? 0n) - (end1.get(partition) ?? 0n);
+        const committedDiff = (com2.get(partition) ?? 0n) - (com1.get(partition) ?? 0n);
+        partitions.push({
+          topic,
+          partition,
+          produceRate: Math.max(0, Number(logEndDiff) / intervalSec),
+          consumeRate: Math.max(0, Number(committedDiff) / intervalSec)
+        });
+      }
+    }
+    partitions.sort(
+      (a, b) => a.topic.localeCompare(b.topic) || a.partition - b.partition
+    );
+    return { intervalMs, partitions };
+  } finally {
+    await admin.disconnect();
+  }
+}
+async function fetchLogEndOffsets(admin, topics) {
+  const entries = await Promise.all(
+    topics.map(async (topic) => {
+      const offsets = await admin.fetchTopicOffsets(topic);
+      const partitionMap = /* @__PURE__ */ new Map();
+      for (const p of offsets) {
+        partitionMap.set(p.partition, BigInt(p.offset));
+      }
+      return [topic, partitionMap];
+    })
+  );
+  return new Map(entries);
+}
+function buildCommittedMap(raw) {
+  const result = /* @__PURE__ */ new Map();
+  for (const topicOffset of raw) {
+    const partitionMap = /* @__PURE__ */ new Map();
+    for (const p of topicOffset.partitions) {
+      partitionMap.set(p.partition, p.offset === "-1" ? 0n : BigInt(p.offset));
+    }
+    result.set(topicOffset.topic, partitionMap);
+  }
+  return result;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/reporter/tableReporter.ts
+import chalk from "chalk";
+import Table from "cli-table3";
+
+// src/types/index.ts
+var VERSION = "0.1.0";
+function classifyLag(lag) {
+  if (lag < 100n) return "OK";
+  if (lag < 1000n) return "WARN";
+  return "HIGH";
+}
+
+// src/reporter/tableReporter.ts
+var LEVEL_ICON = {
+  OK: chalk.green("\u{1F7E2} OK  "),
+  WARN: chalk.yellow("\u{1F7E1} WARN"),
+  HIGH: chalk.red("\u{1F534} HIGH")
+};
+function formatLag(lag) {
+  return lag.toLocaleString();
+}
+function formatRate(rate) {
+  return rate < 0.1 ? "0" : `${rate.toFixed(1)} msg/s`;
+}
+function formatTrend(lagDiff) {
+  if (lagDiff === void 0) return chalk.gray("  -  ");
+  if (lagDiff === 0n) return chalk.gray("  =  ");
+  if (lagDiff > 0n) return chalk.red(`\u25B2 +${lagDiff.toLocaleString()}`);
+  return chalk.green(`\u25BC ${lagDiff.toLocaleString()}`);
+}
+function groupStatus(totalLag) {
+  const level = classifyLag(totalLag);
+  if (level === "OK") return chalk.green("\u2705 OK");
+  if (level === "WARN") return chalk.yellow("\u26A0\uFE0F  WARNING");
+  return chalk.red("\u{1F6A8} CRITICAL");
+}
+function printLagTable(snapshot, rcaResults = [], rateSnapshot, watchMode = false) {
+  const { groupId, broker, collectedAt, partitions, totalLag } = snapshot;
+  if (!watchMode) {
+    console.log("");
+    console.log(chalk.bold.cyan("\u26A1 klag") + chalk.gray(`  v${VERSION}`));
+    console.log("");
+  }
+  console.log(chalk.bold("\u{1F50D} Consumer Group: ") + chalk.white(groupId));
+  console.log(chalk.bold("   Broker:         ") + chalk.white(broker));
+  const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  const localTime = collectedAt.toLocaleString("sv-SE", {
+    timeZone: tz,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false
+  }).replace("T", " ");
+  console.log(
+    chalk.bold("   Collected At:   ") + chalk.gray(`${localTime} (${tz})`)
+  );
+  console.log("");
+  const status = groupStatus(totalLag);
+  const totalStr = chalk.bold(formatLag(totalLag));
+  console.log(`   Group Status : ${status}   Total Lag : ${totalStr}`);
+  console.log("");
+  const hasRate = !!rateSnapshot && rateSnapshot.partitions.length > 0;
+  const hasTrend = watchMode;
+  const rateMap = /* @__PURE__ */ new Map();
+  if (hasRate && rateSnapshot) {
+    for (const r of rateSnapshot.partitions) {
+      rateMap.set(`${r.topic}-${r.partition}`, r);
+    }
+  }
+  const head = [
+    chalk.bold("Topic"),
+    chalk.bold("Partition"),
+    chalk.bold("Committed Offset"),
+    chalk.bold("Log-End Offset"),
+    chalk.bold("Lag"),
+    ...hasTrend ? [chalk.bold("Trend")] : [],
+    chalk.bold("Status"),
+    ...hasRate ? [chalk.bold("Produce Rate"), chalk.bold("Consume Rate")] : []
+  ];
+  const table = new Table({
+    head,
+    colAligns: [
+      "left",
+      "right",
+      "right",
+      "right",
+      "right",
+      ...hasTrend ? ["right"] : [],
+      "center",
+      ...hasRate ? ["right", "right"] : []
+    ],
+    style: { head: [], border: ["grey"] }
+  });
+  let lastTopic = "";
+  for (const p of partitions) {
+    const level = classifyLag(p.lag);
+    const lagStr = level === "HIGH" ? chalk.red(formatLag(p.lag)) : level === "WARN" ? chalk.yellow(formatLag(p.lag)) : chalk.green(formatLag(p.lag));
+    const rateEntry = rateMap.get(`${p.topic}-${p.partition}`);
+    const rateColumns = hasRate ? [
+      chalk.yellow(formatRate(rateEntry?.produceRate ?? 0)),
+      chalk.cyan(formatRate(rateEntry?.consumeRate ?? 0))
+    ] : [];
+    const topicDisplay = p.topic !== lastTopic ? p.topic : "";
+    lastTopic = p.topic;
+    table.push([
+      topicDisplay,
+      String(p.partition),
+      formatLag(p.committedOffset),
+      formatLag(p.logEndOffset),
+      lagStr,
+      ...hasTrend ? [formatTrend(p.lagDiff)] : [],
+      LEVEL_ICON[level],
+      ...rateColumns
+    ]);
+  }
+  console.log(table.toString());
+  console.log("");
+  if (rcaResults.length === 0) return;
+  console.log(chalk.bold("\u{1F50E} Root Cause Analysis"));
+  console.log("");
+  for (const rca of rcaResults) {
+    const typeLabel = `${chalk.bold.yellow(`   [${rca.type}]`)} ${chalk.white(rca.topic)}`;
+    console.log(typeLabel);
+    console.log(chalk.gray(`   \u2192 ${rca.description}`));
+    console.log(chalk.cyan(`   \u2192 Suggestion: ${rca.suggestion}`));
+    console.log("");
+  }
+}
+
+// src/cli/validators.ts
+import { InvalidArgumentError } from "commander";
+function parseInterval(value) {
+  const parsed = parseInt(value, 10);
+  if (Number.isNaN(parsed) || parsed < 1e3) {
+    throw new InvalidArgumentError("--interval must be a number >= 1000ms.");
+  }
+  return parsed;
+}
+function parseBroker(value) {
+  const match = /^[^:]+:(\d+)$/.exec(value);
+  if (!match) {
+    throw new InvalidArgumentError(
+      "--broker format is invalid. Example: localhost:9092"
+    );
+  }
+  const port = parseInt(match[1], 10);
+  if (port < 1 || port > 65535) {
+    throw new InvalidArgumentError(
+      "--broker port must be between 1 and 65535."
+    );
+  }
+  return value;
+}
+function parseTimeout(value) {
+  const parsed = parseInt(value, 10);
+  if (Number.isNaN(parsed) || parsed < 1e3) {
+    throw new InvalidArgumentError("--timeout must be a number >= 1000ms.");
+  }
+  return parsed;
+}
+
+// src/cli/watcher.ts
+import chalk2 from "chalk";
+var MAX_RETRIES = 3;
+function clearScreen() {
+  process.stdout.write("\x1Bc");
+}
+function printWatchHeader(intervalMs, updatedAt) {
+  const intervalSec = intervalMs / 1e3;
+  const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  const timeStr = updatedAt.toLocaleString("sv-SE", {
+    timeZone: tz,
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false
+  });
+  console.log(
+    chalk2.bold.cyan("\u26A1 klag") + chalk2.gray(`  v${VERSION}`) + "  \u2502  " + chalk2.yellow("watch mode") + "  \u2502  " + chalk2.gray(`${intervalSec}s refresh`) + "  \u2502  " + chalk2.gray("Ctrl+C to exit")
+  );
+  console.log(chalk2.gray(`   Last updated: ${timeStr} (${tz})`));
+}
+function printWatchError(message, retryCount, retryIn) {
+  clearScreen();
+  console.log(
+    chalk2.bold.cyan("\u26A1 klag") + chalk2.gray(`  v${VERSION}`) + "  \u2502  " + chalk2.yellow("watch mode") + "  \u2502  " + chalk2.gray("Ctrl+C to exit")
+  );
+  console.log("");
+  console.error(chalk2.red(`   \u274C Error: ${message}`));
+  console.log(
+    chalk2.yellow(`   Retrying ${retryCount}/${MAX_RETRIES}... in ${retryIn}s`)
+  );
+  console.log("");
+}
+function printWatchFatal(message) {
+  clearScreen();
+  console.log(
+    chalk2.bold.cyan("\u26A1 klag") + chalk2.gray(`  v${VERSION}`) + "  \u2502  " + chalk2.yellow("watch mode")
+  );
+  console.log("");
+  console.error(chalk2.red(`   \u274C Error: ${message}`));
+  console.error(
+    chalk2.red(`   All ${MAX_RETRIES} retries failed \u2014 exiting watch mode`)
+  );
+  console.log("");
+}
+function applyDiff(current, previous) {
+  const prevMap = /* @__PURE__ */ new Map();
+  for (const p of previous.partitions) {
+    prevMap.set(`${p.topic}-${p.partition}`, p.lag);
+  }
+  const partitions = current.partitions.map((p) => {
+    const prevLag = prevMap.get(`${p.topic}-${p.partition}`);
+    const lagDiff = prevLag !== void 0 ? p.lag - prevLag : void 0;
+    return { ...p, lagDiff };
+  });
+  return { ...current, partitions };
+}
+async function runOnce(options, noRate, previous) {
+  const snapshot = await collectLag(options);
+  let rateSnapshot;
+  if (!noRate) {
+    const topics = [...new Set(snapshot.partitions.map((p) => p.topic))];
+    const waitSec = (options.intervalMs ?? 5e3) / 1e3;
+    process.stdout.write(
+      chalk2.gray(`  Sampling rates... (waiting ${waitSec}s)   `)
+    );
+    rateSnapshot = await collectRate(options, topics);
+    process.stdout.write(`\r${" ".repeat(50)}\r`);
+  }
+  const rcaResults = analyze(snapshot, rateSnapshot);
+  const snapshotWithDiff = previous ? applyDiff(snapshot, previous) : snapshot;
+  clearScreen();
+  printWatchHeader(options.intervalMs ?? 5e3, snapshot.collectedAt);
+  printLagTable(snapshotWithDiff, rcaResults, rateSnapshot, true);
+  return snapshot;
+}
+function printCountdown(seconds) {
+  return new Promise((resolve) => {
+    let remaining = seconds;
+    const tick = () => {
+      process.stdout.write(
+        `\r${chalk2.gray(`   [\u25CF] Next refresh in ${remaining}s...`)}   `
+      );
+      if (remaining === 0) {
+        process.stdout.write(`\r${" ".repeat(40)}\r`);
+        resolve();
+        return;
+      }
+      remaining--;
+      setTimeout(tick, 1e3);
+    };
+    tick();
+  });
+}
+function getFriendlyMessage(err, broker) {
+  const message = err instanceof Error ? err.message : String(err);
+  if (message.includes("ECONNREFUSED") || message.includes("ETIMEDOUT") || message.includes("Connection error")) {
+    return `Cannot connect to broker (${broker})`;
+  }
+  if (message.includes("Dead state") || message.includes("not found")) {
+    return `Consumer group not found`;
+  }
+  return message;
+}
+async function startWatch(options, noRate) {
+  process.on("SIGINT", () => {
+    console.log(chalk2.gray("\n\n  Watch mode exited\n"));
+    process.exit(0);
+  });
+  const intervalMs = options.intervalMs ?? 5e3;
+  const waitSec = Math.ceil(intervalMs / 1e3);
+  process.stdout.write(chalk2.gray("  Connecting to broker..."));
+  let errorCount = 0;
+  let previousSnapshot;
+  while (true) {
+    try {
+      previousSnapshot = await runOnce(options, noRate, previousSnapshot);
+      errorCount = 0;
+      if (noRate) {
+        await printCountdown(waitSec);
+      }
+    } catch (err) {
+      errorCount++;
+      const message = getFriendlyMessage(err, options.broker);
+      if (errorCount >= MAX_RETRIES) {
+        printWatchFatal(message);
+        process.exit(1);
+      }
+      printWatchError(message, errorCount, waitSec);
+      await printCountdown(waitSec);
+    }
+  }
+}
+
+// src/cli/index.ts
+process.removeAllListeners("warning");
+var program = new Command();
+program.name("klag").description("Kafka consumer lag root cause analyzer").version(VERSION).requiredOption(
+  "-b, --broker <host:port>",
+  "Kafka broker address",
+  parseBroker,
+  "localhost:9092"
+).requiredOption("-g, --group <groupId>", "Consumer group ID").option(
+  "-i, --interval <ms>",
+  "Rate sampling interval in ms",
+  parseInterval,
+  5e3
+).option("-w, --watch", "Watch mode \u2014 refresh every interval").option("-t, --timeout <ms>", "Connection timeout in ms", parseTimeout, 5e3).option(
+  "--no-rate",
+  "Skip rate sampling (faster, no PRODUCER_BURST detection)"
+).option("--json", "Output raw JSON instead of table").action(async (options) => {
+  try {
+    const kafkaOptions = {
+      broker: options.broker,
+      groupId: options.group,
+      intervalMs: options.interval,
+      timeoutMs: options.timeout
+    };
+    if (options.watch) {
+      await startWatch(kafkaOptions, options.rate === false);
+      return;
+    }
+    process.stdout.write(chalk3.gray("  Connecting to broker..."));
+    const snapshot = await collectLag(kafkaOptions);
+    process.stdout.write(`\r${" ".repeat(50)}\r`);
+    let rateSnapshot;
+    if (options.rate !== false) {
+      const topics = [...new Set(snapshot.partitions.map((p) => p.topic))];
+      const waitSec = (kafkaOptions.intervalMs ?? 5e3) / 1e3;
+      process.stdout.write(
+        chalk3.gray(`  Sampling rates... (waiting ${waitSec}s)   `)
+      );
+      rateSnapshot = await collectRate(kafkaOptions, topics);
+      process.stdout.write(`\r${" ".repeat(50)}\r`);
+    }
+    const rcaResults = analyze(snapshot, rateSnapshot);
+    if (options.json) {
+      const serializable = {
+        ...snapshot,
+        totalLag: snapshot.totalLag.toString(),
+        partitions: snapshot.partitions.map((p) => ({
+          ...p,
+          lag: p.lag.toString(),
+          logEndOffset: p.logEndOffset.toString(),
+          committedOffset: p.committedOffset.toString()
+        })),
+        rate: rateSnapshot,
+        rca: rcaResults
+      };
+      console.log(JSON.stringify(serializable, null, 2));
+    } else {
+      printLagTable(snapshot, rcaResults, rateSnapshot);
+    }
+    process.exit(0);
+  } catch (err) {
+    process.stdout.write(`\r${" ".repeat(50)}\r`);
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("ECONNREFUSED") || message.includes("ETIMEDOUT") || message.includes("Connection error") || message.includes("connect ECONNREFUSED")) {
+      console.error(chalk3.red(`
+\u274C Cannot connect to broker
+`));
+      console.error(chalk3.yellow("   Check the following:"));
+      console.error(chalk3.gray(`   \u2022 Is Kafka running: docker ps`));
+      console.error(chalk3.gray(`   \u2022 Broker address: ${options.broker}`));
+      console.error(
+        chalk3.gray(
+          `   \u2022 Port accessibility: nc -zv ${options.broker.split(":")[0]} ${options.broker.split(":")[1]}`
+        )
+      );
+      console.error("");
+      process.exit(1);
+    }
+    if (message.includes("not found") || message.includes("Dead state")) {
+      console.error(chalk3.red(`
+\u274C Consumer group not found
+`));
+      console.error(chalk3.yellow("   Check the following:"));
+      console.error(chalk3.gray(`   \u2022 Group ID: ${options.group}`));
+      console.error(chalk3.gray(`   \u2022 List existing groups:`));
+      console.error(
+        chalk3.gray(
+          `     kafka-consumer-groups.sh --bootstrap-server ${options.broker} --list`
+        )
+      );
+      console.error("");
+      process.exit(1);
+    }
+    console.error(chalk3.red(`
+\u274C Error: ${message}
+`));
+    process.exit(1);
+  }
+});
+program.parse();

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@closeup1202/klag",
+  "version": "0.1.0",
+  "description": "Kafka consumer lag root cause analyzer",
+  "type": "module",
+  "bin": {
+    "klag": "dist/cli/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check ./src",
+    "format": "biome format --write ./src",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "keywords": [
+    "kafka",
+    "consumer-lag",
+    "cli",
+    "debugging",
+    "monitoring",
+    "kafkajs"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/closeup1202/klag.git"
+  },
+  "homepage": "https://github.com/closeup1202/klag#readme",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.3",
+    "kafkajs": "^2.2.4"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.8",
+    "@types/node": "^25.5.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.1"
+  }
+}