Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add paragraph about usage of parent-child relationship #1414

Open
wants to merge 6 commits into
base: main
Choose a base branch
from

Conversation

joaopgrassi
Copy link
Member

@joaopgrassi joaopgrassi commented Sep 17, 2024

Fixes #1282

Changes

Adds a paragraph mentioning the possibility to use the message creation context as a parent of "Process" spans, to achieve a more traditional parent-child trace structure.

Merge requirement checklist

Copy link
Contributor

@lmolkova lmolkova left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, suggesting to add a bit more guidance for parent case

docs/messaging/messaging-spans.md Outdated Show resolved Hide resolved
docs/messaging/messaging-spans.md Outdated Show resolved Hide resolved
docs/messaging/messaging-spans.md Outdated Show resolved Hide resolved
docs/messaging/messaging-spans.md Outdated Show resolved Hide resolved

Exclusively for single messages scenarios, "Process" or "Receive" span MAY
use the message's creation context as its parent, thus achieving a direct
parent-child relationship between producer and consumer(s).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm suggesting to add a bit of additional guidance around the ambient context and defaults.

Suggested change
parent-child relationship between producer and consumer(s).
parent-child relationship between producer and consumer(s). Instrumentations SHOULD document whether they use message creation context as a parent for "Process" spans and MAY provide configuration option allowing users to control this behavior.
It's NOT RECOMMENDED to use message creation context as a parent for "Process" span (by default) if processing usually happens in the scope of another span.
If instrumentation uses message creation context as a parent on "Process" span in the scope of another valid ambient context, it SHOULD set the ambient context as a link on "Process" span to preserve correlation between message processing and that context.
For example, a messaging broker pushes messages to consumers over HTTP and a consumer application has HTTP server and messaging instrumentations enabled. The messaging instrumentation would create "Process" span following one of these possible approaches:
- "Process" span is a child of HTTP server span context and has a link to message creation context. This is the default behavior for this instrumentation.
- "Process" span is a child of message creation context and has two links: one to message creation context and another one to HTTP server span context. This is opt-in behavior.

LMK what you think.

Maybe we can also put it all into a new section like "Using message context as a parent for "Process" spans" so it appears in the TOC?

Copy link
Member Author

@joaopgrassi joaopgrassi Sep 18, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking the same, but to add new headers for Receive spans and Process inside the Consumer spans section. Right now they are all together and I find it a bit hard to follow.

That didn't look good. Nope 😅

I like what you suggested Using message context as a parent for "Process" spans" but I feel maybe it's not so clear for general users? I want to come up with something that easily highlights "how to get a parent-child trace"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: Needs More Approval
Development

Successfully merging this pull request may close these issues.

Messaging: explain that parent could be used in addition to link
4 participants