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

Clarify documentation for current_root_span #9758

Open
timmc-edx opened this issue Jul 8, 2024 · 4 comments
Open

Clarify documentation for current_root_span #9758

timmc-edx opened this issue Jul 8, 2024 · 4 comments
Assignees

Comments

@timmc-edx
Copy link

timmc-edx commented Jul 8, 2024

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.

@timmc-edx timmc-edx changed the title Question: Getting current service entry span? Clarify documentation for current_root_span Jul 9, 2024
@emmettbutler
Copy link
Collaborator

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

@github-actions github-actions bot added the stale label Sep 14, 2024
Copy link
Contributor

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.

@github-actions github-actions bot closed this as not planned Won't fix, can't repro, duplicate, stale Dec 13, 2024
@timmc-edx
Copy link
Author

@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
Copy link
Collaborator

wantsui commented Dec 17, 2024

@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 wantsui self-assigned this Dec 17, 2024
wantsui added a commit that referenced this issue Jan 8, 2025
Following up on #9758, our
current definition of current_root_span is a bit misleading. This
attempts to clarify the definition since in a distributed trace, you
can't actually use this to grab the root span. (The only thing it
consistently returns is "local root").

## Checklist
- [x] PR author has checked that all the criteria below are met
- The PR description includes an overview of the change
- The PR description articulates the motivation for the change
- The change includes tests OR the PR description describes a testing
strategy
- The PR description notes risks associated with the change, if any
- Newly-added code is easy to change
- The change follows the [library release note
guidelines](https://ddtrace.readthedocs.io/en/stable/releasenotes.html)
- The change includes or references documentation updates if necessary
- Backport labels are set (if
[applicable](https://ddtrace.readthedocs.io/en/latest/contributing.html#backporting))

## Reviewer Checklist
- [x] Reviewer has checked that all the criteria below are met 
- Title is accurate
- All changes are related to the pull request's stated goal
- Avoids breaking
[API](https://ddtrace.readthedocs.io/en/stable/versioning.html#interfaces)
changes
- Testing strategy adequately addresses listed risks
- Newly-added code is easy to change
- Release note makes sense to a user of the library
- If necessary, author has acknowledged and discussed the performance
implications of this PR as reported in the benchmarks PR comment
- Backport labels are set in a manner that is consistent with the
[release branch maintenance
policy](https://ddtrace.readthedocs.io/en/latest/contributing.html#backporting)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants