Iceberg troubleshooting and performance tuning for Cloud

[kbatuigas]

Description

Related PR: redpanda-data/docs#1599 (single sourced)

This pull request adds new documentation for Iceberg topics, specifically focusing on performance tuning and troubleshooting. It also updates the navigation and Antora playbook to include these new resources and a relevant documentation branch.

New Iceberg documentation:

• Added a new page for Iceberg performance tuning, providing guidance on optimizing query performance, translation throughput, partitioning, compaction, lag target tuning, and cluster sizing. (modules/manage/pages/iceberg/iceberg-performance-tuning.adoc)
• Added a new troubleshooting guide for Iceberg topics, covering error diagnosis and resolution, including DLQ inspection and record reprocessing. (modules/manage/pages/iceberg/iceberg-troubleshooting.adoc)

Navigation updates:

• Updated the navigation to include links to the new Iceberg performance tuning and troubleshooting pages. (modules/ROOT/nav.adoc)

Antora playbook update:

• Updated the Antora playbook to reference a new documentation branch related to Iceberg stress testing. (local-antora-playbook.yml)

Resolves https://github.com/redpanda-data/documentation-private/issues/
Review deadline:

Page previews

https://deploy-preview-565--rp-cloud.netlify.app/redpanda-cloud/manage/iceberg/iceberg-performance-tuning/
https://deploy-preview-565--rp-cloud.netlify.app/redpanda-cloud/manage/iceberg/iceberg-troubleshooting/

Checks

• New feature
• Content gap
• Support Follow-up
• Small fix (typos, links, copyedits, etc)

[netlify]

✅ Deploy Preview for rp-cloud ready!

Name	Link
🔨 Latest commit	e7ad15b
🔍 Latest deploy log	https://app.netlify.com/projects/rp-cloud/deploys/69fbb0c19494800008d5cee3
😎 Deploy Preview	https://deploy-preview-565--rp-cloud.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bec5b15c-7a52-45a6-a775-8db2106d8299

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This pull request updates the Antora documentation configuration and navigation by switching the included branch from main to DOC-1848-Document-feature-Iceberg-stress-testing in the local playbook configuration. It adds a new navigation entry for an Iceberg troubleshooting page and introduces the corresponding documentation file that includes content sourced from another location using an AsciiDoc include directive with the single-source tag.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• Add migration pages to Cloud #511: Modifies the same Antora config file, site navigation, and adds new pages under the Iceberg documentation directory
• Add Databricks pages in Cloud #321: Updates the Antora playbook branch configuration and modifies the same navigation and Iceberg documentation files
• Add Glue doc to Cloud #363: Modifies the navigation file to update Iceberg section entries and restructures related Iceberg documentation pages

Suggested reviewers

• mattschumpert
• paulohtb6
• micheleRP

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The PR description mentions performance tuning and multiple changes, but only troubleshooting was actually implemented in this PR. The critical issue number placeholder remains unfilled.	Remove references to unimplemented performance tuning page, fill in the actual issue number from the documentation-private repository, and clarify that this PR only adds troubleshooting documentation with navigation and playbook updates.
Title check	❓ Inconclusive	The title mentions 'troubleshooting and performance tuning' but the PR primarily adds a troubleshooting page; performance tuning is not evident in the actual changes.	Clarify the title to accurately reflect the main changes—either 'Add Iceberg troubleshooting documentation to Cloud' if only troubleshooting is covered, or provide details on performance tuning content if present.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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
• Commit unit tests in branch DOC-1848-iceberg-troubleshooting

---

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

[coderabbitai]

🧹 Nitpick comments (1)

local-antora-playbook.yml (1)

18-18: Revert this branch pin before merge.

Using the feature branch is fine for preview, but please switch this back to main before merging to avoid stale local build config after the docs PR branch is removed.

Based on learnings: in this docs workflow, local-antora-playbook.yml is temporarily pointed at companion docs branches for preview and then reverted to main before merge.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@local-antora-playbook.yml` at line 18, The branches array in
local-antora-playbook.yml is temporarily pinned to the feature branch
DOC-1848-Document-feature-Iceberg-stress-testing; change that entry back to main
by replacing that branch name with main in the branches list (the line
containing "branches: [DOC-1848-Document-feature-Iceberg-stress-testing, v/*,
shared, site-search]" should read with main instead of the feature branch) so
the playbook uses the main companion docs branch before merging.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@local-antora-playbook.yml`:
- Line 18: The branches array in local-antora-playbook.yml is temporarily pinned
to the feature branch DOC-1848-Document-feature-Iceberg-stress-testing; change
that entry back to main by replacing that branch name with main in the branches
list (the line containing "branches:
[DOC-1848-Document-feature-Iceberg-stress-testing, v/*, shared, site-search]"
should read with main instead of the feature branch) so the playbook uses the
main companion docs branch before merging.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: edc606fb-b0a6-4180-b21b-196a65fe4e06

📥 Commits

Reviewing files that changed from the base of the PR and between 160e580 and 0844e68.

📒 Files selected for processing (3)

• local-antora-playbook.yml
• modules/ROOT/nav.adoc
• modules/manage/pages/iceberg/iceberg-troubleshooting.adoc

[micheleRP]

@kbatuigas should you add a blurb for this to the Cloud What's New, so users know about it?

[micheleRP]

@kbatuigas before you merge 1599, please doublecheck for build errors; e.g., the Troubleshoot errors link here: https://deploy-preview-565--rp-cloud.netlify.app/redpanda-cloud/manage/iceberg/migrate-to-iceberg-topics/#troubleshoot-common-migration-issues

[micheleRP]

please see my suggestions before merging

[kbatuigas]

@kbatuigas should you add a blurb for this to the Cloud What's New, so users know about it?

We'll leave it out of What's New in Cloud, we haven't added this to What's New in Self-managed either since there are no new features added.