Extension Propagator B3 Laravel Package

Technical Evaluation

Architecture fit — B3 is a wire-format propagator: it extracts b3/X-B3-* headers inbound and injects them outbound. In a Laravel app it sits at the edge of the request lifecycle — registered on the OpenTelemetry SDK's propagator interface via a service provider, or wrapped in global middleware. Architectural footprint is essentially zero: no data model, no schema, no API surface, no controller changes. It is only meaningful if the app already runs the open-telemetry/opentelemetry-php SDK; standalone it does nothing. The package is a native PHP extension (compile-and-load, not Composer-only), which is the single most consequential fact for a TPM: it converts a code dependency into an infrastructure dependency.

Integration feasibility — Two install steps with very different risk profiles. The Composer side is a one-line require and a config binding — trivial. The native side requires phpize/build-essential and a .so compiled against the exact PHP ABI in every runtime: local dev containers, CI, staging, production, and every worker/cron image. Feasible in standard Linux Docker; friction or outright blockers on Laravel Vapor (custom Lambda runtime rebuild), shared hosting, Windows dev machines, and any PaaS without build hooks. No prebuilt binaries are published — validate this early, because it determines whether one platform engineer can own it or every app team must.

Technical risk — Moderate, concentrated in four areas: (1) ABI/version coupling — every PHP minor upgrade forces a rebuild and smoke test; (2) supply chain — you are compiling C in CI and should pin commit + checksum; (3) the repo is a [READONLY] subtree split with 0 stars and 0 dependents, so no issue tracker, no PRs, no changelog here, and near-zero battle-testing in the wild — you will be an early adopter, not a follower; (4) stranding — if the extension lags an SDK release, your upgrade path is blocked. The unasked question underneath all of it: propagators are microseconds of work, so the extension's value is throughput at scale, not capability. If a pure-PHP B3 propagator exists in the SDK or contrib, this package is a performance optimization you can defer indefinitely.

Key questions

• Is B3 a hard interoperability requirement (Istio/Envoy default, Spring Cloud Sleuth, Zipkin) or a nice-to-have? Which upstream callers actually speak it?
• Does a pure-PHP B3 propagator exist in the SDK/contrib we can use instead, and what is its measured per-request cost on our workload?
• Do we need B3 single-header, multi-header, or both?
• Which PHP versions, architectures (amd64/arm64), and libc (glibc/musl) must we support?
• Who owns native extension builds — platform/infra or the app team?
• Does the extension keep pace with the SDK's release cadence? Check the upstream monorepo's commit history before committing.

Integration Approach

Stack fit — Laravel 10/11/12 on the OTel PHP SDK, registered as a composite propagator alongside W3C tracecontext and baggage so B3-speaking callers and W3C-speaking callers both work during any transition period. Configuration-driven (env flag) rather than hardcoded, so it can be enabled per service. No conflict with existing middleware, logging, or queue instrumentation. Works on FPM and Octane alike.

Migration path — Verify the capability gap first: if B3 interop is required only for one upstream dependency, scope it to that service rather than the fleet. Attempt the Composer-only path before adopting the native extension; only take on the build burden if there is no pure-PHP implementation or if profiling shows propagation cost is material. Then roll out environment-by-environment: dev images → CI → staging → one production service → fleet.

Compatibility — The real compatibility matrix is not Laravel, it's the runtime: PHP minor version, ZTS vs NTS, glibc vs musl (Alpine), amd64 vs arm64 (Graviton, Apple Silicon dev machines). Multi-arch builds are the usual tripwire and the usual source of schedule slip. Also pin the Composer package constraint against the SDK version in use.

Sequencing

1. Spike (1–2 days): build the extension in a throwaway Docker image, confirm headers are extracted and injected correctly against an Envoy/Istio test double.
2. Decide: native extension vs pure-PHP alternative, based on measured overhead and interop requirement.
3. Bake into the base image with a pinned commit and checksum; add multi-arch CI build (3–5 days of platform time).
4. Wire into a service provider behind a config flag; add a startup assertion that the propagator is actually registered.
5. Validate end-to-end trace continuity in staging (correct parent-child across a B3 boundary), then enable per service. Budget roughly one sprint of elapsed time, mostly platform, not application.

Operational Impact

Maintenance — The read-only split means no local issue tracker, no PRs, no changelog; upgrades ride the upstream monorepo release cadence and you consume them wholesale. You own the build artifacts. Every PHP minor bump in the base image triggers a rebuild plus a trace smoke test — add it as an explicit line item to the PHP upgrade runbook. Track the pinned commit and watch upstream activity as a leading indicator of abandonment.

Support — No vendor, no paid support, no meaningful community around this specific repo. Escalation path is the OTel PHP GitHub/Slack in the parent monorepo. With zero dependents, edge cases will be novel to you. Assign a named internal owner and document the build recipe; otherwise this becomes tribal knowledge and dies with the person who set it up.

Scaling — The extension exists to make per-request propagation cheaper, so the benefit scales with request volume and is invisible at low RPS. At hundreds of RPS the win is likely in the noise; the business case appears fleet-wide at high throughput. Cost side: marginally larger images, longer CI builds, and one more artifact to distribute. Image size and cold start are otherwise unaffected since compilation happens at build time.

Failure modes

• Extension fails to load → fatal at boot. Loud and safe, but means a bad PHP upgrade takes down the service rather than degrading it.
• Extension loads but propagator isn't registered → silent loss of trace context; traces fragment with no error. Mitigate with a boot-time assertion and a synthetic trace check in CI.
• B3 single-header vs multi-header mismatch with the peer → orphaned spans, visible only in trace QA, not in logs or metrics.
• Upstream not propagating B3 → broken trace chains that will be attributed to this package regardless of fault.
• Version lag behind a required SDK release → hard block on an unrelated upgrade, discovered mid-sprint.

Ramp-up — Low for application developers (config plus a service provider registration, hours). Moderate-to-high for platform: native builds, multi-arch CI, caching, and a release process for the .so. Reckon one engineer-day of learning for a platform engineer already comfortable with phpize, and a hard dependency on that person existing.

TPM verdict — Conditional go. Adopt only if B3 interop is a confirmed hard requirement, no pure-PHP propagator is acceptable on performance grounds, and a platform team will own multi-arch native builds and the PHP-upgrade rebuild cycle. If any of those three is false, this is a deferred optimization rather than a dependency worth taking on.