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

Attention: Patch coverage is 77.77778% with 4 lines in your changes missing coverage. Please review.

Please upload report for BASE (main@68b1b43). Learn more about missing BASE report.

Files	Patch %	Lines
src/API/Logs/LateBindingLogger.php	0.00%	2 Missing :warning:
src/API/Trace/LateBindingTracer.php	0.00%	2 Missing :warning:

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1310   +/-   ##
=======================================
  Coverage        ?   74.21%           
  Complexity      ?     2584           
=======================================
  Files           ?      373           
  Lines           ?     7430           
  Branches        ?        0           
=======================================
  Hits            ?     5514           
  Misses          ?     1916           
  Partials        ?        0           

Flag	Coverage Δ
8.1	73.82% <66.66%> (?)
8.2	74.11% <77.77%> (?)
8.3	74.03% <77.77%> (?)
8.4	74.02% <77.77%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files	Coverage Δ
src/API/Trace/LocalRootSpan.php	100.00% <100.00%> (ø)
src/API/Trace/Span.php	94.44% <100.00%> (ø)
src/API/Logs/LateBindingLogger.php	60.00% <0.00%> (ø)
src/API/Trace/LateBindingTracer.php	60.00% <0.00%> (ø)

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 68b1b43...e6fb45d. Read the comment docs.

[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.