Clarify documentation for current_root_span

[timmc-edx]

The documentation for ddtrace.Tracer.current_root_span is ambiguous regarding whether this is A) the root span of the entire trace, B) the root span of the current process, or C) the service entry span:

• « Returns the root span of the current execution. » -- implies B
• « useful for attaching information related to the trace as a whole » -- implies A

Reading the source code, this line implies B, at least to my eyes.

It would be great if the docs could be made clear on this point.

[emmettbutler]

Thanks for noting this, @timmc-edx. We'll clarify the docs.

[github-actions]

This issue has been automatically closed after a period of inactivity. If it's a
feature request, it has been added to the maintainers' internal backlog and will be
included in an upcoming round of feature prioritization. Please comment or reopen
if you think this issue was closed in error.

[timmc-edx]

@emmettbutler Is this something you're still planning on fixing? It got auto-closed as stale but I don't see any changes to the docs.

[wantsui]

@timmc-edx - Thanks for reporting this, I have taken an attempt at trying to clarify this wording with #11764 and need the rest of the team to review, but I agree with you that it should be your interpretation of B, which is really the "local" root span, versus the root span each time. I see we use the term "local" root span in the other tracers, ie: https://docs.datadoghq.com/tracing/trace_collection/custom_instrumentation/java/dd-api/#adding-tags .

To clarify this a bit further in case anyone else stumbles upon this:

In a distributed trace assuming two python applications, ie: AppA --> AppB:

• the current_root_span returned in AppA would be the actual root since AppA started the request.
• the current_root_span returned in AppB would then be the first span that started in AppB, which is also usually the service entry span.

[wantsui]

@timmc-edx The changes clarifying the current_root_span usage have been merged in: https://ddtrace.readthedocs.io/en/stable/api.html?highlight=current_root_span#ddtrace.trace.Tracer.current_root_span . Let me know if there are any further concerns!

[wantsui]

Thanks for confirming (with the emoji)! I'll close this issue now. Feel free to reopen if there are any concerns!