fix: improve discoverability of partition_autobalancing_mode and redpanda_memory_allocated_memory#1656
Conversation
…anda_memory_allocated_memory Closes redpanda-data#1508 Closes redpanda-data#1503 partition_autobalancing_mode (cluster-balancing.adoc): - Added explicit [[partition_autobalancing_mode]] anchor to the Partition balancing settings section so the property is reachable by URL fragment and indexed by site search - Added rpk commands showing how to get and set the property - Clarified that node_add is the default without an enterprise license and continuous is the default with one redpanda_memory_allocated_memory (public-metrics-reference.adoc): - Expanded the entry to explain why the metric can appear high even without memory pressure (batch cache inclusion) - Clarified when to use this metric vs redpanda_memory_available_memory - Added example PromQL queries for per-shard and per-broker views
✅ Deploy Preview for redpanda-docs-preview ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThis pull request updates documentation across two AsciiDoc files to address gaps in searchability and clarity. The first change expands the Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@modules/reference/pages/public-metrics-reference.adoc`:
- Around line 892-900: The docs are inconsistent: update the monitoring page
text in monitor-health.adoc to match the new definition that
redpanda_memory_allocated_memory includes reclaimable batch cache memory; change
the wording where it currently states allocated memory excludes reclaimable
cache to instead state it includes reclaimable batch cache memory and update any
alerting guidance/examples to recommend using redpanda_memory_available_memory
for measuring actual free memory (and adjust any formulas that presumed
allocated excluded reclaimable memory).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: dd0fc0f5-38cb-489d-b45f-80331fe70480
📒 Files selected for processing (2)
modules/manage/pages/cluster-maintenance/cluster-balancing.adocmodules/reference/pages/public-metrics-reference.adoc
- Add TeachYAR and GibTrain (Gibraltar Compliance) project cards. Extend Project interface with an optional live URL and a "Live site" button. GibTrain links to its GitHub Pages deployment. - Add "Open-source contributions" subsection listing five docs PRs: graphprotocol/docs#1096, open-telemetry/opentelemetry.io#9711, redpanda-data/docs#1656, OWASP/CheatSheetSeries#2101 and #2100. Styled with repo code-tag, state pill, and PR number. - Home page copy: "Tech writer" -> "All things docs", "My writer journey" -> "My journey". - Expand the Ably entry with the docs re-engineering work (Textile -> Next.js + TypeScript + React) and link the two merged MDX conversion PRs: ably/docs#2911 (REST API) and #2913 (SSE). - Expand docs/ably/index.md with a new "Re-engineering the docs site" section plus images across SSE, webhooks, pub/sub, troubleshooting, and architecture. Add a troubleshooting subsection linking ably/docs#2984 (HAR file guide) and #2818 (service disruptions). - Rename static/img/ably/ably-troubleshooting/ (drop the trailing space in the directory name that was breaking image references). - Remove em-dashes from site content (projects page, 3 blog post alt-texts) using contextual substitutions: colons for titles and list intros, commas/periods for mid-sentence pauses, parens for a parenthetical, pipe for the HTML page title. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
micheleRP
left a comment
micheleRP
left a comment
There was a problem hiding this comment.
Final review pass
Files reviewed: 2 .adoc files
Overall: Small, focused discoverability fix that cleanly addresses both linked issues. One cross-page inconsistency (flagged by CodeRabbit) is worth resolving before merge, plus a few minor style nits.
Issue alignment
Closes #1508 and #1503 — both addressed:
- #1508 — property now has a stable URL fragment plus actionable
rpkcommands on the management page. - #1503 — metric now explains what kind of memory it measures (including reclaimable batch cache) and points to
redpanda_memory_available_memoryfor pressure monitoring.
Critical — cross-page inconsistency
modules/manage/partials/monitor-health.adoc:65 (not in this PR) contradicts the new definition:
public-metrics-reference.adoc:892(new): "…includes memory in the batch cache that has been allocated but could be reclaimed."monitor-health.adoc:65(existing): "…since allocated does not include reclaimable cache memory."
The PR's definition is the correct one — the formulas right below on monitor-health.adoc (available / (free + allocated)) only make numeric sense if allocated includes reclaimable batch cache. The old wording was already wrong; this PR just makes the contradiction more visible.
Fix: Either update monitor-health.adoc:65 in this PR, or open a follow-up and link it from the PR description. This is the same issue CodeRabbit flagged on its inline comment — it's a valid finding.
Suggestions
-
cluster-balancing.adoc:123— back-to-back repetition of "enterprise license."- Current: "This is the default setting for clusters with an enterprise license. It requires an enterprise license."
- Suggested: "This is the default setting for clusters with an enterprise license, which it requires."
- The auto-generated
cluster-properties.adocpartial already has a NOTE explaining license-based defaults, so no need to over-explain here.
-
public-metrics-reference.adoc:900— same-page xref could be a shortcut reference.- Current:
xref:reference:public-metrics-reference.adoc#redpanda_memory_available_memory[`redpanda_memory_available_memory`] - Suggested:
<<redpanda_memory_available_memory,`redpanda_memory_available_memory`>> - Style only; the full xref works. Shortcut form is idiomatic for same-page anchors.
- Current:
-
public-metrics-reference.adoc:902–907— the first PromQL block is just the bare metric name. "Query Prometheus directly" oversells a block that contains onlyredpanda_memory_allocated_memory.- Suggested: Reframe as "To see raw per-shard values," or fold the per-shard example into the surrounding sentence and keep only the
sum by (instance)query in a code block.
- Suggested: Reframe as "To see raw per-shard values," or fold the per-shard example into the surrounding sentence and keep only the
Impact on other files
modules/manage/partials/monitor-health.adoc— see critical finding above.- Nav — both pages already in
modules/ROOT/nav.adoc(lines 165, 305). No change needed. - Existing deep links to
cluster-balancing.adoc— all target#intra-broker-partition-balancing; the new anchor doesn't collide. - No What's New / release-notes entry needed — discoverability fix, not a feature.
What works well
- Fixes a genuine pre-existing error on
cluster-balancing.adoc:116: "Redpanda allocates brokers to random healthy brokers" → "Redpanda allocates partitions to random healthy brokers." - License-based default story on the manage page now matches the auto-generated
cluster-properties.adocNOTE block. - Bidirectional pointers between
redpanda_memory_allocated_memoryandredpanda_memory_available_memoryhelp readers pick the right metric. [[partition_autobalancing_mode]]anchor is placed above the section header, giving a stable URL fragment independent of the section title.
|
@franrob-projects thank you for this PR! I'll have an SME review the final version, but we do have some initial suggestions we can implement. Would you like to review these, or do you want me to take it over from here? |
- Align monitor-health.adoc memory paragraph with the corrected redpanda_memory_allocated_memory definition (allocated includes reclaimable batch cache memory). - Collapse repeated "enterprise license" sentence in the partition_autobalancing_mode continuous row. - Use shortcut xref for the same-page redpanda_memory_available_memory link and tighten the per-shard PromQL lead-in. - Lowercase "intra-broker partition balancing" in the overview table. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…e continuous row Splits the back-reference clause into two sentences to remove ambiguity about what "which" refers to. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
| === redpanda_memory_allocated_memory | ||
|
|
||
| Total memory allocated (in bytes) per CPU shard. | ||
| Total memory allocated (in bytes) per CPU shard. This includes all memory currently held by Redpanda on that shard, including memory in the batch cache that has been allocated but could be reclaimed. |
There was a problem hiding this comment.
nit: that could be reclaimed if needed.
4 participants
Summary
Addresses two issues where users reported finding no search results for configuration and metrics properties that are documented but not easily discoverable.
Closes #1508
Closes #1503
partition_autobalancing_mode (
cluster-balancing.adoc)The property was referenced only as an xref to the reference partial, with no anchor on the manage-side page itself. Users searching for
partition_autobalancing_modelanded nowhere actionable.Changes:
[[partition_autobalancing_mode]]anchor directly to the Partition balancing settings section, making it reachable by URL fragment and indexed by site searchrpk cluster config getandrpk cluster config setcommands so users know immediately how to inspect and change the valuenode_addwithout an enterprise license,continuouswith oneredpanda_memory_allocated_memory (
public-metrics-reference.adoc)The original entry was two sentences. Users trying to understand what this metric measures — particularly why it can read high without the system being under memory pressure — had no explanation.
Changes:
redpanda_memory_available_memoryChecks
Preview pages