adding LocalRootSpan

[brettmc]

this is based on Java's implementation, https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/v2.3.0/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/LocalRootSpan.java and adds the ability to identify and locate the "local root span" in a trace. The local root span is the top-level active span which has either an invalid or remote parent. It's tracked automatically as part of making a span active, either via Span::activate() or Span::storeInContext(), and can be retrieved in a couple of ways, but most easily via LocalRootSpan::current().

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 74.30%. Comparing base (eaba9e3) to head (9f1bbec). Report is 1 commits behind head on main.

Additional details and impacted files

[](https://app.codecov.io/gh/open-telemetry/opentelemetry-php/pull/1310?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry) ```diff @@ Coverage Diff @@ ## main #1310 +/- ## ============================================ + Coverage 74.28% 74.30% +0.02% - Complexity 2491 2498 +7 ============================================ Files 353 354 +1 Lines 7135 7149 +14 ============================================ + Hits 5300 5312 +12 - Misses 1835 1837 +2 ``` | [Flag](https://app.codecov.io/gh/open-telemetry/opentelemetry-php/pull/1310/flags?src=pr&el=flags&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry) | Coverage Δ | | |---|---|---| | [8.1](https://app.codecov.io/gh/open-telemetry/opentelemetry-php/pull/1310/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry) | `73.98% <85.71%> (-0.02%)` | :arrow_down: | | [8.2](https://app.codecov.io/gh/open-telemetry/opentelemetry-php/pull/1310/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry) | `74.22% <100.00%> (-0.01%)` | :arrow_down: | | [8.3](https://app.codecov.io/gh/open-telemetry/opentelemetry-php/pull/1310/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry) | `74.20% <100.00%> (+0.03%)` | :arrow_up: | | [8.4](https://app.codecov.io/gh/open-telemetry/opentelemetry-php/pull/1310/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry) | `74.26% <100.00%> (+0.07%)` | :arrow_up: | Flags with carried forward coverage won't be shown. [Click here](https://docs.codecov.io/docs/carryforward-flags?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry#carryforward-flags-in-the-pull-request-comment) to find out more. | [Files](https://app.codecov.io/gh/open-telemetry/opentelemetry-php/pull/1310?dropdown=coverage&src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry) | Coverage Δ | | |---|---|---| | [src/API/Trace/LocalRootSpan.php](https://app.codecov.io/gh/open-telemetry/opentelemetry-php/pull/1310?src=pr&el=tree&filepath=src%2FAPI%2FTrace%2FLocalRootSpan.php&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry#diff-c3JjL0FQSS9UcmFjZS9Mb2NhbFJvb3RTcGFuLnBocA==) | `100.00% <100.00%> (ø)` | | | [src/API/Trace/Span.php](https://app.codecov.io/gh/open-telemetry/opentelemetry-php/pull/1310?src=pr&el=tree&filepath=src%2FAPI%2FTrace%2FSpan.php&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry#diff-c3JjL0FQSS9UcmFjZS9TcGFuLnBocA==) | `94.44% <100.00%> (+0.69%)` | :arrow_up: | ... and [1 file with indirect coverage changes](https://app.codecov.io/gh/open-telemetry/opentelemetry-php/pull/1310/indirect-changes?src=pr&el=tree-more&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry) ------ [Continue to review full report in Codecov by Sentry](https://app.codecov.io/gh/open-telemetry/opentelemetry-php/pull/1310?dropdown=coverage&src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry). > **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry) > `Δ = absolute (impact)`, `ø = not affected`, `? = missing data` > Powered by [Codecov](https://app.codecov.io/gh/open-telemetry/opentelemetry-php/pull/1310?dropdown=coverage&src=pr&el=footer&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry). Last update [eaba9e3...9f1bbec](https://app.codecov.io/gh/open-telemetry/opentelemetry-php/pull/1310?dropdown=coverage&src=pr&el=lastupdated&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=open-telemetry).

[brettmc]

The primary objective here is to make it easier to go back and modify the local root span of a transaction. We do this now (by stashing the root span in context and accessing it later) in some auto-instrumentation packages to do things like update the name once routing has taken place, and in a similar fashion we could also add further attributes that were not known at the time the root span was created.