Skip to content

feat: scoped dependencies bridge interop + inferred-spans orphan fix - #126

Merged
intuibase merged 7 commits into
open-telemetry:mainfrom
intuibase:feat/custom-instrumentation-bridge-and-inferred-spans-fix
Jul 2, 2026
Merged

intuibase merged 7 commits into
open-telemetry:mainfrom
intuibase:feat/custom-instrumentation-bridge-and-inferred-spans-fix

Conversation

@intuibase

@intuibase intuibase commented Jul 2, 2026 •

Copy link
Copy Markdown
Contributor

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), so
their spans join the distro's traces instead of silently going to a no-op provider.
Gated behind the new OTEL_PHP_SCOPED_DEPS_BRIDGE_ENABLED option.

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 side
effect: instrumentation the application writes itself against the public unscoped
OpenTelemetry\* API runs against a separate runtime — its spans use a no-op tracer
provider 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, default false)

  • New ScopedDepsBridge class encapsulates the whole feature (kept out of
    the already-long PhpPartFacade, which now just calls ScopedDepsBridge::load()).
  • When enabled, before the app's Composer autoloader runs, it requires a generated
    unscoped_api_aliases.php that registers class_alias() entries mapping the unscoped
    OpenTelemetry\API\* / OpenTelemetry\Context\* / OpenTelemetry\SDK\* classes onto
    the distro's scoped implementations. The app's instrumentation then transparently uses
    the distro's tracer provider and context.
  • The alias file is generated at build time by 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).
  • No-op when scoping is disabled (OTEL_PHP_SCOPED_DEPS_ENABLED=false): without scoping
    the distro already uses the unscoped classes, so no bridging is needed.

2. Version-mismatch warnings

  • When the bridge is enabled, at shutdown the distro checks whether the app has installed
    different versions of open-telemetry/api, open-telemetry/context, or open-telemetry/sdk
    than the versions it bundles (the bundled versions are the ones actually used at runtime),
    and logs a warning per mismatch.
  • App versions are read via the app's own 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.
  • Also detects the "app loaded its own API class before the alias was applied" case and
    warns that the runtimes are not shared.

3. Inferred-spans orphan fix

  • InferredSpans held the pushed scope as a WeakReference; when a third-party POST hook
    detached the scope out of order (the Context::storage()->scope() anti-pattern, e.g. in
    opentelemetry-auto-curl), the scope could be GC'd and any child spans orphaned.
  • Now holds a strong reference to the scope, and on endFrameSpan() inspects the
    ScopeInterface::DETACHED flag: if the scope was already detached externally, the span is
    still 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

  • RootSpan now saves the root scope it attaches and uses it directly in the shutdown
    handler, instead of relying on Context::storage()->scope() which can return the wrong
    scope when user instrumentation attaches/detaches scopes out of order.

intuibase added 5 commits July 1, 2026 18:24
…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.
@intuibase intuibase changed the title Custom instrumentation interop and inferred-spans orphan fix feat: custom instrumentation interop and inferred-spans orphan fix Jul 2, 2026
- 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.
@intuibase
intuibase marked this pull request as ready for review July 2, 2026 13:09
@intuibase
intuibase requested a review from a team as a code owner July 2, 2026 13:09
@intuibase
intuibase requested a review from SergeyKleyman July 2, 2026 13:09
@intuibase intuibase self-assigned this Jul 2, 2026

@SergeyKleyman SergeyKleyman left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
@intuibase intuibase changed the title feat: custom instrumentation interop and inferred-spans orphan fix feat: scoped dependencies bridge interop + inferred-spans orphan fix Jul 2, 2026
@intuibase
intuibase merged commit 9d2a4fc into open-telemetry:main Jul 2, 2026
67 checks passed
@intuibase
intuibase deleted the feat/custom-instrumentation-bridge-and-inferred-spans-fix branch July 2, 2026 16:09
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

Successfully merging this pull request may close these issues.

Custom OpenTelemetry instrumentations do not share the EDOT PHP 1.5+ scoped runtime

2 participants