Improve Kafka documentation - #286
Conversation
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
Note
|
| Layer / File(s) | Summary |
|---|---|
Consumer & Producer API Contracts en/docs/connectors/catalog/messaging/kafka/actions.md |
Producer sendWithMetadata() clarifies nullable offset and timestamp; Consumer adds autoSeekOnValidationFailure config option, warns that subscribe() panics without groupId, makes duration parameters optional across eight operations (defaulting to -1), and adds new offsetsForTimes operation with parameters and return shape. |
Connector Overview & Version Reference en/docs/connectors/catalog/messaging/kafka/connector-overview.md |
Connector version updated from v4.6.3 to v4.6.5; trigger reference updated to point to BytesConsumerRecord payload structure. |
onConsumerRecord Callback Signature Documentation en/docs/connectors/catalog/messaging/kafka/triggers.md |
onConsumerRecord handler signature documentation expanded to list three parameter-order variants (caller-first, records-first, caller-optional), clarifying that records array may be typed for automatic deserialization and optionally marked readonly, and that @kafka:Payload annotation may explicitly designate payload records. |
Integration Example Code en/docs/develop/integration-artifacts/event/kafka.md |
Kafka listener example rewritten with configurable bootstrapServers, groupId, and kafkaTopic; handler signature changed from typed OrderEvent[] to AnydataConsumerRecord[] requiring manual deserialization; adds per-message error handling and logging; removes inline OrderEvent type and onError handler. |
Estimated code review effort
🎯 2 (Simple) | ⏱️ ~12 minutes
Poem
I nibble docs in morning light,
v4.6.5 tuned just right.
Callbacks hum and params bend,
Examples guide from start to end.
🐇🍃
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)
| Check name | Status | Explanation | Resolution |
|---|---|---|---|
| Description check | The description includes a filled Purpose section with clear goals and related links, but most required template sections (Goals, Approach, User stories, Release note, Documentation, Training, Certification, Marketing, Automation tests, Security checks, Samples, Migrations, Test environment, Learning) are empty placeholders rather than substantive content. | Complete the empty template sections: expand Goals, Approach, User stories, Release note, Documentation, Training, Certification, Marketing, Automation tests, Security checks, Samples, Migrations, Test environment, and Learning with specific details relevant to the Kafka documentation updates. |
✅ Passed checks (4 passed)
| Check name | Status | Explanation |
|---|---|---|
| Title check | ✅ Passed | The title 'Improve Kafka documentation' directly and accurately summarizes the main change—comprehensive updates to Kafka connector documentation covering syntax corrections, configuration clarifications, and enhanced consumer/producer guidance. |
| 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
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 help to get the list of available commands and usage tips.
![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
🧹 Nitpick comments (1)
en/docs/develop/integration-artifacts/event/kafka.md (1)
73-75: Consider using the officialballerina/data.jsondatalibrary for JSON string deserialization.The
ensureType()call without an explicit type argument (line 73) is valid—the compiler infersbyte[]from the variable declaration via contextual typing.However,
fromJsonStringWithType()(line 75) is used in multiple documentation examples but is not an officially documented API. Ballerina's official recommendation for deserializing JSON strings to user-defined types is theballerina/data.jsondatalibrary'sparseString()function, which provides a well-documented, library-based approach instead of relying on undocumented method patterns.🤖 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/integration-artifacts/event/kafka.md` around lines 73 - 75, The docs use an undocumented method pattern: keep the ensureType() call as-is (it can remain inferencing byte[]), but replace the undocumented json deserialization call OrderEvent orderEvent = check jsonStr.fromJsonStringWithType(); with the official ballerina/data.jsondata library: import data.jsondata and use its parseString() API to parse jsonStr and then convert/assign the result to the user-defined OrderEvent type (e.g., call jsondata:parseString(jsonStr) and map/convert to OrderEvent or use the library's typed parsing pattern), so the example uses the documented parseString() flow instead of fromJsonStringWithType().
🤖 Prompt for all review comments with 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.
Inline comments:
In `@en/docs/connectors/catalog/messaging/kafka/triggers.md`:
- Around line 98-111: The note incorrectly shows a non-existent `@kafka`:Payload
annotation; remove that example and replace it with guidance to use a typed
parameter for implicit payload binding (e.g., reference the service method
signature onConsumerRecord and the parameter MyRecord[] records) so the
connector will deserialize Kafka message bytes into the typed records
automatically; update the example line that currently reads remote function
onConsumerRecord(kafka:Caller caller, `@kafka`:Payload MyRecord[] records) returns
error? to instead show using the typed parameter (remote function
onConsumerRecord(kafka:Caller caller, MyRecord[] records) returns error?) and
adjust the surrounding text to state that payload binding is implicit and driven
by the parameter type.
---
Nitpick comments:
In `@en/docs/develop/integration-artifacts/event/kafka.md`:
- Around line 73-75: The docs use an undocumented method pattern: keep the
ensureType() call as-is (it can remain inferencing byte[]), but replace the
undocumented json deserialization call OrderEvent orderEvent = check
jsonStr.fromJsonStringWithType(); with the official ballerina/data.jsondata
library: import data.jsondata and use its parseString() API to parse jsonStr and
then convert/assign the result to the user-defined OrderEvent type (e.g., call
jsondata:parseString(jsonStr) and map/convert to OrderEvent or use the library's
typed parsing pattern), so the example uses the documented parseString() flow
instead of fromJsonStringWithType().
🪄 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: 247d72c9-621b-4eab-bd56-4af47aeaddd4
⛔ Files ignored due to path filters (2)
en/static/img/connectors/catalog/messaging/kafka/kafka_producer_screenshots_05_operation_filled.pngis excluded by!**/*.pngen/static/img/connectors/catalog/messaging/kafka/kafka_producer_screenshots_06_completed_flow.pngis excluded by!**/*.png
📒 Files selected for processing (4)
en/docs/connectors/catalog/messaging/kafka/actions.mden/docs/connectors/catalog/messaging/kafka/connector-overview.mden/docs/connectors/catalog/messaging/kafka/triggers.mden/docs/develop/integration-artifacts/event/kafka.md
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with 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.
Inline comments:
In `@en/docs/develop/integration-artifacts/event/kafka.md`:
- Around line 94-101: The example in onConsumerRecord references the OrderEvent
type but doesn't declare it, making the snippet non-runnable; add a brief
OrderEvent record definition (with fields used like orderId and any other fields
consumed by processOrder) above or within the example or add a clear comment
pointing to its declaration in functions.bal, and ensure the doc shows the
OrderEvent symbol so readers can copy a complete, runnable sample that compiles
with onConsumerRecord and processOrder.
🪄 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: 00c62276-12e9-4025-848f-880e1fa68e8c
📒 Files selected for processing (6)
en/docs/connectors/catalog/messaging/kafka/actions.mden/docs/connectors/catalog/messaging/kafka/connector-overview.mden/docs/connectors/catalog/messaging/kafka/example.mden/docs/connectors/catalog/messaging/kafka/setup-guide.mden/docs/connectors/catalog/messaging/kafka/triggers.mden/docs/develop/integration-artifacts/event/kafka.md
✅ Files skipped from review due to trivial changes (3)
- en/docs/connectors/catalog/messaging/kafka/setup-guide.md
- en/docs/connectors/catalog/messaging/kafka/example.md
- en/docs/connectors/catalog/messaging/kafka/connector-overview.md
🚧 Files skipped from review as they are similar to previous changes (1)
- en/docs/connectors/catalog/messaging/kafka/triggers.md
2 participants
Purpose
Improve the Kafka document content with correct syntax and guidelines. Enhance the instruction to use the publisher and consumer flows of the Kafka Connector to improve maintainability and error tracking.
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
New Features
Behavior Changes
Documentation