Add the troubleshooting section#457
Conversation
📝 WalkthroughWalkthroughThis PR adds six troubleshooting documentation pages (errors & stack traces, logging, deployment, profiling, strand-dump analysis, IDE troubleshooting) and updates the site sidebar to include a Troubleshooting section linking the new pages. ChangesTroubleshooting Documentation Suite
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
ESLint skipped: no ESLint configuration detected in root package.json. To enable, add 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 |
|
@CodeRabbit-ai review |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: Length of output: 54393
Review Summary🔴 Blocker
An unresolved TODO placeholder is present inside the document body: <!-- TODO: example dump -->This will render as a visible HTML comment in some Docusaurus setups (or at minimum leave a gap in the page). Either add a representative strand dump example here or remove the comment before merging. 🟠 Issues1. The
Either update the 2. Unverified The "Reuse context across calls with child loggers" and "Custom loggers" sections use log:Logger requestLog = log:createLogger("orders", requestId = requestId);
requestLog.printInfo("Validating order");The standard 3. Possibly missing image reference in Line 61 of This image path ( 4. Misleading bash comment in Inside the Docker shell code block, a TOML instruction is embedded as a comment: # In Ballerina.toml: [build-options] cloud = "docker"
bal buildInline comments in shell blocks about a separate file's contents are easy to miss. Consider presenting the 🟡 Suggestions5. No index/overview page for the Troubleshooting section All other sections under 6. Inconsistent frontmatter Only 7. Inconsistent section footer heading Four pages end with |
samithkavishke
force-pushed
the
troubleShootingMain
branch
from
ac85ebb to
3450316
Compare
samithkavishke
requested review from
KavinduZoysa,
anupama-pathirage and
rosensilva
as code owners
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (1)
en/docs/develop/troubleshooting/deployment.md (1)
19-26: ⚡ Quick winSeparate TOML configuration from shell commands for clarity.
Line 20 places TOML as a bash comment, which is easy to miss and can confuse copy-paste flows. Show
Ballerina.tomlin its owntomlblock and keep the shell block command-only.♻️ Proposed patch
-Build the image: - -```bash -# In Ballerina.toml: [build-options] cloud = "docker" -bal build +Set `Ballerina.toml`: + +```toml +[build-options] +cloud = "docker" +``` + +Build the image: + +```bash +bal build # Docker artifacts in: target/docker/<package-name>/ docker build -t myapp:latest target/docker/myapp/ docker run -p 9090:9090 myapp:latest</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@en/docs/develop/troubleshooting/deployment.mdaround lines 19 - 26, The docs
mix TOML config with shell commands which can be confusing; separate the
Ballerina.toml snippet from the shell block: add a toml block showing
[build-options] cloud = "docker" (referencing Ballerina.toml and the
[build-options] key) and then keep the shell block containing only commands (bal
build, docker build -t myapp:latest target/docker/myapp/, docker run -p
9090:9090 myapp:latest) with a short preceding sentence like "Set
Ballerina.toml:" and "Build the image:" to make copy-paste clear.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.Inline comments:
In@en/docs/develop/troubleshooting/errors-and-stack-traces.md:
- Line 2: The front-matter key sidebar_position is set to 1 but the PR notes
show this page should be position 2; update the front-matter by changing the
sidebar_position value from 1 to 2 (or remove the sidebar_position entry
entirely to let the explicit sidebar ordering control placement) so the page
ordering matches the troubleshooting nav.- Around line 31-38: The code blocks in errors-and-stack-traces.md are unlabeled
(e.g., the blocks starting with "Compiling source", "ERROR
[service.bal:(5:1,5:1)] remote methods...", "error: compilation failed", "error:
{ballerina/http}ClientRequestError...", "at /...", and the
TypeCastError stack) and should be labeled to satisfy MD040 and Prism
highlighting; update each triple-backtick fence for those snippets (and the
additional ranges 65-76, 92-94, 110-115, 152-155, 175-177, 198-202) to usesuch as "Compiling source", "ERROR [...]", "error: compilation failed", "error: {ballerina/http}ClientRequestError", "at <org>/<package>:<version>:<function>(<file>.bal:<line>)", and "error: {ballerina}TypeCastError ...") becomes ```bash ... ```; ensure you only change the fence markers, not the block contents. In `@en/docs/develop/troubleshooting/ide-troubleshooting.md`: - Line 2: The front-matter key sidebar_position is set to 6 but should match the documented ordering for IDE troubleshooting; update the sidebar_position value from 6 to 1 (change the sidebar_position: 6 line to sidebar_position: 1) so the IDE troubleshooting section appears in the correct position in the sidebar. In `@en/docs/develop/troubleshooting/logging.md`: - Line 2: The frontmatter key sidebar_position in logging.md is set to 2 but should match the intended troubleshooting order (position 4) or be omitted; update the frontmatter entry "sidebar_position" to 4 (or remove the key entirely if the sidebar is controlled elsewhere) so the page ordering aligns with the repo's navigation configuration and rebuilds with the correct position. In `@en/docs/develop/troubleshooting/strand-dump-analysis.md`: - Line 2: The frontmatter key sidebar_position currently set to 4 is out of sync with the PR ordering notes that place this page at position 6; update the sidebar_position value from 4 to 6 (or remove the sidebar_position entry entirely if your global sidebar config is authoritative) so the metadata matches the intended navigation order and avoid misleading frontmatter. --- Nitpick comments: In `@en/docs/develop/troubleshooting/deployment.md`: - Around line 19-26: The docs mix TOML config with shell commands which can be confusing; separate the Ballerina.toml snippet from the shell block: add a toml block showing [build-options] cloud = "docker" (referencing Ballerina.toml and the [build-options] key) and then keep the shell block containing only commands (bal build, docker build -t myapp:latest target/docker/myapp/, docker run -p 9090:9090 myapp:latest) with a short preceding sentence like "Set Ballerina.toml:" and "Build the image:" to make copy-paste clear.🪄 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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID:
4da7bc85-112d-4766-927a-967435753670⛔ Files ignored due to path filters (7)
en/static/img/develop/troubleshooting/ide-troubleshooting/ballerina-output-channel.pngis excluded by!**/*.pngen/static/img/develop/troubleshooting/ide-troubleshooting/open-settings-command.pngis excluded by!**/*.pngen/static/img/develop/troubleshooting/ide-troubleshooting/settings-page.pngis excluded by!**/*.pngen/static/img/develop/troubleshooting/logging/configurable-variables.pngis excluded by!**/*.pngen/static/img/develop/troubleshooting/logging/log-error.pngis excluded by!**/*.pngen/static/img/develop/troubleshooting/profiling/report.pngis excluded by!**/*.pngen/static/img/develop/troubleshooting/strand-dump-analysis/strand-dump-output-format.svgis excluded by!**/*.svg📒 Files selected for processing (7)
en/docs/develop/troubleshooting/deployment.mden/docs/develop/troubleshooting/errors-and-stack-traces.mden/docs/develop/troubleshooting/ide-troubleshooting.mden/docs/develop/troubleshooting/logging.mden/docs/develop/troubleshooting/profiling.mden/docs/develop/troubleshooting/strand-dump-analysis.mden/sidebars.ts
samithkavishke
force-pushed
the
troubleShootingMain
branch
from
7d1eb79 to
761ce67
Compare
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
samithkavishke
force-pushed
the
troubleShootingMain
branch
from
761ce67 to
7438b41
Compare
There was a problem hiding this comment.
♻️ Duplicate comments (2)
en/docs/develop/troubleshooting/errors-and-stack-traces.md (2)
2-2:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAlign frontmatter order with troubleshooting nav order.
Line 2 still sets
sidebar_position: 1, but this page is ordered as item 2 in the troubleshooting section. Please change to2(or removesidebar_positionand rely on explicit sidebar config).♻️ Proposed fix
-sidebar_position: 1 +sidebar_position: 2🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@en/docs/develop/troubleshooting/errors-and-stack-traces.md` at line 2, The frontmatter key `sidebar_position` in this document is set to 1 but the page should be the second item in the troubleshooting section; update the frontmatter by changing `sidebar_position: 1` to `sidebar_position: 2` (or remove the `sidebar_position` line entirely to rely on the explicit sidebar configuration) so the ordering matches the troubleshooting nav.
31-38:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd language identifiers to fenced code blocks.
These fences are still unlabeled, which triggers MD040 and reduces syntax-highlighting consistency. Use
bashon each affected block.♻️ Proposed fix
-``` +```bash Compiling source myorg/mypackage:1.0.0 @@ error: compilation contains errors-
+bash
Compiling source
myorg/mypackage:1.0.0
@@
We thank you for helping make us better.-``` +```bash ERROR [service.bal:(5:1,5:1)] remote methods are not allowed in HTTP service-
+bash
error: compilation failed
java.lang.ClassCastException: class org.wso2.ballerinalang.compiler.tree.BLangFunction
@@
at io.ballerina.stdlib.http.compiler.HttpServiceValidator.validate(HttpServiceValidator.java:120)-``` +```bash error: <message> [<detail>]-
+bash
at /::(.bal:)-``` +```bash error: {ballerina}TypeCastError {"message":"incompatible types: 'string' cannot be cast to 'int'"} at myorg/mypackage:0.1.0:processData(utils.bal:42) at myorg/mypackage:0.1.0:main(main.bal:10)</details> Based on learnings: “In the wso2/docs-integrator Docusaurus documentation, Prism does not support using `text` or `console` as language identifiers... label the fence with `bash` instead.” Also applies to: 65-76, 92-94, 110-115, 152-155, 173-175, 196-200 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@en/docs/develop/troubleshooting/errors-and-stack-traces.mdaround lines 31 -
38, Label every unlabeled fenced code block in the file with the bash language
identifier; specifically change the blocks that start with "Compiling source",
the block showing "ERROR [main.bal:(12:5,12:5)]", the "ERROR
[service.bal:(5:1,5:1)]" block, the "error: compilation failed" stacktrace
block, the "error: []" block, the "at
/::(.bal:)" block, and the "error:
{ballerina}TypeCastError ..." block so each openingbecomesbash; also
apply the same change to the other unlabeled blocks referenced (65-76, 92-94,
110-115, 152-155, 173-175, 196-200) to satisfy Prism/Docusaurus highlighting
expectations.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.Duplicate comments:
In@en/docs/develop/troubleshooting/errors-and-stack-traces.md:
- Line 2: The frontmatter key
sidebar_positionin this document is set to 1
but the page should be the second item in the troubleshooting section; update
the frontmatter by changingsidebar_position: 1tosidebar_position: 2(or
remove thesidebar_positionline entirely to rely on the explicit sidebar
configuration) so the ordering matches the troubleshooting nav.- Around line 31-38: Label every unlabeled fenced code block in the file with
the bash language identifier; specifically change the blocks that start with
"Compiling source", the block showing "ERROR [main.bal:(12:5,12:5)]", the "ERROR
[service.bal:(5:1,5:1)]" block, the "error: compilation failed" stacktrace
block, the "error: []" block, the "at
/::(.bal:)" block, and the "error:
{ballerina}TypeCastError ..." block so each openingbecomesbash; also
apply the same change to the other unlabeled blocks referenced (65-76, 92-94,
110-115, 152-155, 173-175, 196-200) to satisfy Prism/Docusaurus highlighting
expectations.</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Path: .coderabbit.yaml **Review profile**: CHILL **Plan**: Pro **Run ID**: `f3d2558c-7aa6-4527-9e40-eb55d8eeab4b` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 761ce67e933fb620c2d35426956825dbcd0cceed and 7438b41494f1d128010fe0ebdd83dc4f20696e7e. </details> <details> <summary>⛔ Files ignored due to path filters (7)</summary> * `en/static/img/develop/troubleshooting/ide-troubleshooting/ballerina-output-channel.png` is excluded by `!**/*.png` * `en/static/img/develop/troubleshooting/ide-troubleshooting/open-settings-command.png` is excluded by `!**/*.png` * `en/static/img/develop/troubleshooting/ide-troubleshooting/settings-page.png` is excluded by `!**/*.png` * `en/static/img/develop/troubleshooting/logging/configurable-variables.png` is excluded by `!**/*.png` * `en/static/img/develop/troubleshooting/logging/log-error.png` is excluded by `!**/*.png` * `en/static/img/develop/troubleshooting/profiling/report.png` is excluded by `!**/*.png` * `en/static/img/develop/troubleshooting/strand-dump-analysis/strand-dump-output-format.svg` is excluded by `!**/*.svg` </details> <details> <summary>📒 Files selected for processing (7)</summary> * `en/docs/develop/troubleshooting/deployment.md` * `en/docs/develop/troubleshooting/errors-and-stack-traces.md` * `en/docs/develop/troubleshooting/ide-troubleshooting.md` * `en/docs/develop/troubleshooting/logging.md` * `en/docs/develop/troubleshooting/profiling.md` * `en/docs/develop/troubleshooting/strand-dump-analysis.md` * `en/sidebars.ts` </details> <details> <summary>✅ Files skipped from review due to trivial changes (5)</summary> * en/docs/develop/troubleshooting/strand-dump-analysis.md * en/sidebars.ts * en/docs/develop/troubleshooting/deployment.md * en/docs/develop/troubleshooting/ide-troubleshooting.md * en/docs/develop/troubleshooting/logging.md </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
3 participants
Purpose
Goals
Approach
User stories
Release note
Documentation
Training
Certification
Marketing
Automation tests
Security checks
Samples
Related PRs
Migrations (if applicable)
Test environment
Learning
Summary by CodeRabbit