docs: add correlation IDs tutorial to address distributed tracing #3636
Conversation
Manancode
requested review from
quetzalliwrites and
asyncapi-bot-eve
as code owners
WalkthroughA new documentation guide titled Correlation IDs has been added. The guide explains the role of correlation IDs in AsyncAPI for distributed tracing within event-driven architectures. It covers the definition, importance, and various implementation methods including YAML examples and a practical Node.js AMQP usage example that demonstrates generating, propagating, and logging correlation IDs. The document outlines best practices for unique ID generation and consistent usage across services. Changes
Sequence Diagram(s)sequenceDiagram
participant Publisher as Order Publisher
participant AMQP as AMQP Broker
participant Consumer as Order Consumer
Publisher->>AMQP: Generate & send order message with correlation ID in headers
AMQP->>Consumer: Deliver order message with correlation ID
Consumer->>Consumer: Log and trace message using the correlation ID
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
asyncapi-bot
requested review from
BhaswatiRoy,
J0SAL,
TRohit20 and
VaishnaviNandakumar
✅ Deploy Preview for asyncapi-website ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site configuration. |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #3636 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 20 20
Lines 732 732
=========================================
Hits 732 732 ☔ View full report in Codecov by Sentry. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
markdown/docs/tutorials/correlation-ids.md (4)
7-9: Introduction Section ClarityThe introduction provides a concise and informative overview of the guide. Consider adding a brief pointer or a link to further reading (e.g., a link to AsyncAPI documentation) to help users dive deeper into the context if needed.
10-17: Correlation IDs Overview and Bullet ListThe explanation of key components (Original Request, Message Chain, and Correlation ID) is clear and lays a solid foundation.
- Suggestion: In the bullet for "Message Chain" (line 15), consider adding an article for better readability (e.g., "a series of messages exchanged between different services").
🧰 Tools
🪛 LanguageTool
[uncategorized] ~15-~15: Possible missing article found.
Context: ...a business transaction - Message Chain: Series of messages exchanged between different...(AI_HYDRA_LEO_MISSING_A)
93-118: Node.js Example: publishOrder MethodThe
publishOrdermethod correctly generates a correlation ID and includes it in both the message and the headers.
- Suggestion: While the example code is instructional, consider a comment noting that in production code, additional error handling might be added around the AMQP calls.
120-134: Node.js Example: consumeOrder MethodThe consume function correctly retrieves and logs the correlation ID.
- Suggestion: Consider wrapping the message processing (e.g., the JSON parsing on line 126) in a try-catch block to handle potential parsing errors gracefully, ensuring robust error handling in real-world scenarios.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
markdown/docs/tutorials/correlation-ids.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
markdown/docs/tutorials/correlation-ids.md
[uncategorized] ~15-~15: Possible missing article found.
Context: ...a business transaction - Message Chain: Series of messages exchanged between different...
(AI_HYDRA_LEO_MISSING_A)
⏰ Context from checks skipped due to timeout of 180000ms (1)
- GitHub Check: Lighthouse CI
🔇 Additional comments (11)
markdown/docs/tutorials/correlation-ids.md (11)
1-6: Front Matter and Metadata StructureThe YAML front matter is well-formed and clearly sets the title, description, and weight for the tutorial. This metadata will help with proper ordering and navigation on the website.
18-25: Purpose of Correlation IDsThis section effectively outlines why correlation IDs are important, with clear, bulleted points. The structure is easy to follow.
26-32: Implementation Methods OverviewThe list of methods for implementing correlation IDs (Message Headers, Payload Fields, Middleware) is straightforward and informative.
35-78: AsyncAPI YAML ExampleThe YAML snippet is comprehensive and well-formatted. It clearly demonstrates how to define correlation IDs within an AsyncAPI specification, including the proper placement in message headers.
- Suggestion: You might mention, optionally, any reference to standards like
x-correlation-idif it aligns with industry practices, though the current example is perfectly acceptable per the tutorial’s intent.
80-82: Practical Implementation IntroductionThe introductory text for the Node.js with AMQP example sets the stage nicely for the code example that follows.
83-92: Node.js Example: Module Imports and Connection SetupThe import statements and the
connectmethod ofOrderServiceare implemented clearly. The asynchronous connection to AMQP and channel creation are well demonstrated.
137-158: Usage Example and Main FunctionThe usage example clearly demonstrates how to both consume and publish orders. This practical snippet ties the tutorial together effectively.
160-168: Best Practices SectionThe best practices for implementing correlation IDs are well outlined and easy to follow. This section adds significant practical value to the tutorial by summarizing the key takeaways.
169-182: Mermaid Sequence DiagramThe sequence diagram provides an effective visual representation of how correlation IDs are propagated through the system. It enhances the documentation by offering a clear, concise flow of interactions.
184-190: Monitoring and Debugging GuidelinesThis section is succinct and effectively stresses the importance of correlation IDs in tracking, analyzing, and debugging distributed transactions.
191-196: Conclusion and Final ReminderThe conclusion reiterates the importance of correlation IDs and the “Remember” block offers a helpful tip for implementation. The structure is clear and reinforces the overall message of the tutorial.
|
One of the tests is failing during the artifact upload step when using the lighthouse-ci-action. The issue appears to be related to the artifact name lighthouse-results. The artifact name should be changed to a valid format. I would be happy to raise a PR to update the default artifact name if this is confirmed as an issue |
There was a problem hiding this comment.
Hey @Manancode , Is this PR ready for review?
CC @fmvilas or @derberg can one of you give a technical go-ahead for the same first please?
|
Yes @TRohit20 the PR is ready to review. Please go through the content and diagrams used in the deployed-preview |
Solves Tutorials: Correlation IDs #9
Added new tutorial explaining correlation IDs and their implementation in AsyncAPI
Summary by CodeRabbit