BE: Fall back to per-topic rates for cluster throughput when broker aggregate is absent

[Sangyong-Jeon]

• Breaking change?

What changes did you make? (Give an overview)

Closes #1874.

When the per-broker topic-less BrokerTopicMetrics aggregate is absent from the scraped metrics, InternalClusterState resolved cluster bytesInPerSec/bytesOutPerSec to null ("0 B/s") even though every per-topic rate was scraped successfully. This affects brokers that don't surface the topic-less aggregate over JMX (observed on Confluent cp-kafka 7.9.7): the cluster dashboard shows 0 throughput while topic details show real numbers.

InternalClusterState now falls back to summing the per-topic rates when the per-broker map is empty. This is exact, since bytes in/out are additive across topics and counted once at the leader broker, so sum(per-topic) == all-topics broker aggregate.

Is there anything you'd like reviewers to focus on?

Whether the fallback belongs in InternalClusterState (cluster aggregate) or IoRatesMetricsScanner (per-broker). The per-broker map can't be reconstructed in the scanner because topicBytes*PerSec is already cluster-wide (merged across brokers), so the cluster aggregate is the correct layer for the fallback. Per-broker dashboard values for such brokers remain a separate, lower-impact gap.

How Has This Been Tested? (put an "x" (case-sensitive!) next to an item)

• Unit checks

• Added InternalClusterStateTest: per-broker present (used as-is), per-broker empty + per-topic present (fallback), both empty (null).
• Manually validated the root cause against a cp-kafka 7.9.7 broker: the global BrokerTopicMetrics:BytesInPerSec MBean is present via JmxTool but absent from kafka-ui's scraped set; per-topic throughput populated, cluster shows 0.

Checklist (put an "x" (case-sensitive!) next to all the items, otherwise the build will fail)

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (e.g. ENVIRONMENT VARIABLES)
• My changes generate no new warnings (e.g. Sonar is happy)
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged

Summary by CodeRabbit

• Bug Fixes
  • Enhanced cluster-wide I/O throughput metrics calculation with improved fallback mechanisms to ensure accurate reporting across different data availability scenarios.
  • Added comprehensive test coverage for metrics aggregation logic.

[kapybro]

AI Summary

The issue describes a problem where Kafka UI's cluster dashboard incorrectly shows zero throughput when the per-broker topic-less BrokerTopicMetrics aggregate is missing, even though per-topic rates are available. The proposed solution is to fall back to summing per-topic rates when the per-broker map is empty, as the sum of per-topic rates equals the broker aggregate. The fallback logic is placed in InternalClusterState rather than IoRatesMetricsScanner because the cluster aggregate is the correct layer for this calculation. Unit tests and manual validation confirm the fix works.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 266d05db-8a01-48f9-b88d-4ed33514b24d

📥 Commits

Reviewing files that changed from the base of the PR and between c842552 and f451c60.

📒 Files selected for processing (2)

• api/src/main/java/io/kafbat/ui/model/InternalClusterState.java
• api/src/test/java/io/kafbat/ui/model/InternalClusterStateTest.java

---

📝 Walkthrough

Walkthrough

This PR updates InternalClusterState to compute cluster-wide byte I/O rates more robustly. A new sumWithTopicFallback helper method aggregates per-broker rates when available, falling back to per-topic rates when broker JMX metrics omit topic-less aggregates. The new behavior is tested with three cases covering broker-rate usage, topic-rate fallback, and null handling.

Changes

Fallback aggregation for cluster IO rates

Layer / File(s)	Summary
Rate aggregation helper implementation api/src/main/java/io/kafbat/ui/model/InternalClusterState.java	Adds java.util.Map import, introduces sumWithTopicFallback(@nullable) static method that sums broker-level IO rates when present or falls back to per-topic rates, and integrates it into bytesInPerSec and bytesOutPerSec computation.
Rate aggregation helper tests api/src/test/java/io/kafbat/ui/model/InternalClusterStateTest.java	New test class validates sumWithTopicFallback behavior: returns broker-rate sum when present, falls back to topic-rate sum when broker rates are empty, and returns null when both sources lack data.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• Cluster/broker throughput shows 0 B/s despite per-topic rates being populated #1874: This PR directly implements the fallback aggregation behavior (summing per-topic rates when per-broker aggregates are missing) described in that issue.

Poem

A rabbit hops through broker rates with care, 🐰
When JMX data isn't there,
Topic aggregates come to the rescue bright,
Fallback logic makes the metrics right! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding a fallback mechanism to use per-topic rates for cluster throughput when the broker aggregate is absent, which directly matches the implementation in InternalClusterState.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Hi Sangyong-Jeon! 👋

Welcome, and thank you for opening your first PR in the repo!

Please wait for triaging by our maintainers.

Please take a look at our contributing guide.

[Sangyong-Jeon]

Real-world verification on Confluent cp-kafka

Built this PR's branch into a Docker image (JDK 25) and ran it side by side with the current ghcr.io/kafbat/kafka-ui:latest image against the same Confluent cp-kafka 3.9 broker over JMX (METRICS_TYPE=JMX) — same cluster, 64 topics, 118 partitions, live traffic.

Cluster throughput	latest	this PR
Production (bytesInPerSec)	0 Bytes	3 KB/s
Consumption (bytesOutPerSec)	0 Bytes	2 KB/s

This broker only surfaces per-topic BrokerTopicMetrics in the scraped set (the topic-less aggregate is not present), so latest resolves the cluster aggregate to null → "0 Bytes" even though every per-topic rate is scraped correctly. With the per-topic fallback the aggregate reflects real traffic. (Both instances run with identical config — only the throughput differs; the live rate fluctuates over time.)

latest (before):

this PR (after):

InternalClusterStateTest and checkstyleMain pass on JDK 25.