Repository navigation
feat: scoped dependencies bridge interop + inferred-spans orphan fix - #126
Merged
intuibase merged 7 commits intoJul 2, 2026
Conversation
…trumentation interop Allows user code using the standard unscoped OpenTelemetry PHP API (open-telemetry/api, open-telemetry/context) to share the same TracerProvider, Context storage, and Propagator as EDOT PHP's scoped runtime. When OTEL_PHP_CUSTOM_INSTRUMENTATION_ENABLED=true: - Registers class_alias() mappings from OTelDistroScoped\OpenTelemetry\* to OpenTelemetry\* before the user's autoloader runs - User hook() registrations and span creation transparently use EDOT PHP's SDK - Spans from custom instrumentation appear in the same trace as EDOT PHP spans Also saves the root span scope in RootSpan to avoid incorrect scope detach when user instrumentation uses Context::storage()->scope() out of order. The alias file (unscoped_api_aliases.php) is generated at build time by tools/build/generate_unscoped_api_aliases.php and placed alongside the scoped vendor directory.
…d externally Third-party auto-instrumentation hooks (curl, psr18, http-async, etc.) use the anti-pattern Context::storage()->scope() in their POST hooks to retrieve their scope. When InferredSpans pushes scopes onto the context chain during a timer tick (between the PRE and POST of such a hook), the POST hook detaches the wrong scope — an InferredSpans scope instead of its own. Previously, InferredSpans stored each frame scope as a WeakReference. When the scope was detached externally, it was immediately garbage-collected along with its context and span. At the next tick, the WeakRef resolved to null and the span was never ended, causing child spans (started while the InferredSpans scope was active) to reference a non-exported parent → orphaned spans. Fix: store frame scopes as strong references instead of WeakReferences. This keeps the scope object (and the context/span it holds) alive until InferredSpans processes the frame at the next tick. ContextStorageNode::detach() safely returns ScopeInterface::DETACHED when called on an already-detached scope; InferredSpans detects this flag and calls span->end() to export the span, ensuring child spans are not orphaned.
…on bridge
Extract the custom instrumentation bridge into a dedicated
CustomInstrumentationBridge class (out of the already-long PhpPartFacade) and
alias the scoped open-telemetry/sdk classes in addition to api/context, so user
instrumentation that touches SDK types shares the distro's runtime too.
At shutdown, when OTEL_PHP_CUSTOM_INSTRUMENTATION_ENABLED=true, warn if the app's
installed open-telemetry/{api,context,sdk} versions differ from the versions the
distro bundles (the ones actually used at runtime via the scoped runtime and the
unscoped bridge). The bridge is skipped early when scoping is disabled
(scoped_deps_enabled=false), since without scoping the distro already uses the
unscoped classes and no alias/version reconciliation is needed.
Add the option to the configuration reference with a note explaining the custom instrumentation interop: why the scoped runtime isolates the app's own OpenTelemetry instrumentation, what enabling the bridge does (shared tracer provider/context, connected user-installed auto-instrumentation), the version-mismatch warnings for api/context/sdk, and that it is a no-op when scoping is disabled.
- PhpPartFacade debug pre/post hooks used the same Context::storage()->scope() anti-pattern that InferredSpans/RootSpan were just fixed for; track our own scope via a LIFO stack instead so third-party context manipulation (e.g. bridged user instrumentation) can't cause the wrong scope to be read/detached. - CustomInstrumentationBridge had no alias-validity probe class for open-telemetry/sdk, so a broken SDK bridge produced no warning when app and distro SDK versions happened to match. Add OpenTelemetry\SDK\Sdk as the probe.
- CustomInstrumentationBridgeTest (component): drives the bridge end-to-end through a spawned app-code process. The app's own unscoped open-telemetry/sdk always auto-registers a TracerProvider via the inherited OTEL_EXPORTER_OTLP_ENDPOINT (PhpPartFacade forces OTEL_PHP_AUTOLOAD_ENABLED=true before the app's autoloader runs), so the custom span is always exported either way - what differs is whether it joins the root span's trace (bridge enabled) or becomes its own disconnected root (bridge disabled). - CustomInstrumentationBridgeVersionWarningTest (unit): exercises warnIfVersionMismatch() via Reflection, forcing the probe classes (Globals, Context, Sdk) to autoload unscoped first to deterministically reproduce the "app won the race" case and assert a warning is logged per package.
SergeyKleyman
approved these changes
Jul 2, 2026
Contributor
There was a problem hiding this comment.
It looks good.
I would consider naming that stresses “bridge” part and not “custom instrumentation” since the feature can also be used with the officially published auto instrumentation packages that are not included in the distro. Config option can be named something like OTEL_PHP_SCOPED_DEPS_BRIDGE_ENABLED and classes prefix to ScopedDepsBridge*.
OTEL_PHP_CUSTOM_INSTRUMENTATION_ENABLED -> OTEL_PHP_SCOPED_DEPS_BRIDGE_ENABLED
SergeyKleyman
approved these changes
Jul 2, 2026
intuibase
deleted the
feat/custom-instrumentation-bridge-and-inferred-spans-fix
branch
July 2, 2026 16:09
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a bridge that lets an application's own (unscoped) OpenTelemetry dependencies
share the distro's scoped runtime (tracer provider + context) — this covers both
instrumentation the application writes itself and officially published
auto-instrumentation packages it installs on its own (e.g.
opentelemetry-auto-pdo), sotheir spans join the distro's traces instead of silently going to a no-op provider.
Gated behind the new
OTEL_PHP_SCOPED_DEPS_BRIDGE_ENABLEDoption.Along the way it fixes an inferred-spans bug that could orphan child spans, and adds a
startup/shutdown safety net around scope handling.
Resolves the interop problem described in elastic/elastic-otel-php#386.
Motivation
The distro ships its OpenTelemetry dependencies scoped (namespaces prefixed with
OTelDistroScoped\) to avoid clashing with the application's own dependencies. A sideeffect: instrumentation the application writes itself against the public unscoped
OpenTelemetry\*API runs against a separate runtime — its spans use a no-op tracerprovider and an empty context, so they are neither exported nor connected to the
distro's traces.
What changed
1. Scoped dependencies bridge (
OTEL_PHP_SCOPED_DEPS_BRIDGE_ENABLED, defaultfalse)ScopedDepsBridgeclass encapsulates the whole feature (kept out ofthe already-long
PhpPartFacade, which now just callsScopedDepsBridge::load()).requires a generatedunscoped_api_aliases.phpthat registersclass_alias()entries mapping the unscopedOpenTelemetry\API\*/OpenTelemetry\Context\*/OpenTelemetry\SDK\*classes ontothe distro's scoped implementations. The app's instrumentation then transparently uses
the distro's tracer provider and context.
tools/build/generate_unscoped_api_aliases.php(parses the scoped vendor, emits aliases for API/Context/SDK; traits are skipped —
class_alias()does not support them).OTEL_PHP_SCOPED_DEPS_ENABLED=false): without scopingthe distro already uses the unscoped classes, so no bridging is needed.
2. Version-mismatch warnings
different versions of
open-telemetry/api,open-telemetry/context, oropen-telemetry/sdkthan the versions it bundles (the bundled versions are the ones actually used at runtime),
and logs a warning per mismatch.
Composer\InstalledVersions::getPrettyVersion().The class name is assembled at runtime so php-scoper does not rewrite it to the scoped
OTelDistroScoped\Composer\InstalledVersions(which would report the distro's versions).Pretty versions match the bundled form, so no normalisation is needed.
warns that the runtimes are not shared.
3. Inferred-spans orphan fix
InferredSpansheld the pushed scope as aWeakReference; when a third-party POST hookdetached the scope out of order (the
Context::storage()->scope()anti-pattern, e.g. inopentelemetry-auto-curl), the scope could be GC'd and any child spans orphaned.endFrameSpan()inspects theScopeInterface::DETACHEDflag: if the scope was already detached externally, the span isstill ended (kept alive by the strong ref) so children are not orphaned. The strong ref is
released each sampling tick, so there is no leak.
4. Root-span scope safety
RootSpannow saves the root scope it attaches and uses it directly in the shutdownhandler, instead of relying on
Context::storage()->scope()which can return the wrongscope when user instrumentation attaches/detaches scopes out of order.