Weave Code
Extension Propagator B3 Laravel Package
open-telemetry/extension-propagator-b3
Provides B3 (Zipkin-style) context propagation for OpenTelemetry PHP, letting you read and inject single- or multi-header B3 trace headers alongside or instead of the default W3C Trace Context. Useful for services interoperating with Zipkin, Brave, or other B3-based tracing systems.
[READONLY] b3 propagator
Frequently asked questions about Extension Propagator B3
- What does open-telemetry/extension-propagator-b3 actually do?
- It is a B3 propagator for the OpenTelemetry PHP SDK. It extracts B3 and X-B3-* headers from inbound requests and injects them on outbound calls, so trace context survives across services that speak the Zipkin/Brave wire format. It does not collect spans or export data itself; it only handles context propagation at the edge of the request lifecycle. Standalone, without the OpenTelemetry SDK installed and configured, it does nothing.
- Do I need this package in a Laravel application?
- Only if you already run the open-telemetry/opentelemetry-php SDK and must interoperate with B3-based systems such as Zipkin, Brave, Spring Cloud Sleuth, or an Istio/Envoy mesh using B3 by default. If all your callers speak W3C Trace Context, the SDK default is sufficient and this package adds no value. Confirm which upstream callers genuinely send B3 headers before adopting it.
- How do I install it, and is it just a Composer package?
- No, it is not Composer-only. The Composer step is a single require plus binding the propagator on the SDK configuration, but the package is a native PHP extension compiled with phpize and build tools and loaded as a .so. Every runtime image needs that compiled artifact built against the exact PHP ABI: local dev containers, CI, staging, production, and each queue or cron worker image.
- Does it support both B3 single header and B3 multi-header formats?
- It covers the B3 format family, which includes the single-header b3 value and the multi-header X-B3-TraceId, X-B3-SpanId, X-B3-ParentSpanId, X-B3-Sampled, and X-B3-Flags form. Decide explicitly which of the two your upstream and downstream systems use, since a partial match will silently break trace continuity. Verify the exact header set you need against the upstream monorepo before you commit.
- Which Laravel and PHP versions are supported?
- The meaningful compatibility matrix is not Laravel versions but the PHP runtime: PHP minor version, ZTS versus NTS builds, glibc versus musl, and amd64 versus arm64. The package works anywhere the OpenTelemetry PHP SDK works, so Laravel 10, 11, and 12 are all fine in principle. Because the extension compiles against a specific ABI, every PHP minor upgrade forces a rebuild and a smoke test.
- Can I run B3 alongside W3C Trace Context in the same Laravel app?
- Yes, and that is the recommended approach during any transition period. Register it as part of a composite propagator that includes W3C tracecontext and baggage, so B3-speaking callers and W3C-speaking callers both work. Drive the choice with an environment flag rather than hardcoding it, so you can enable B3 per service instead of across the whole fleet.
- Will it work on Laravel Vapor, Alpine, or shared hosting?
- Standard Linux Docker on glibc and amd64 is the comfortable path. Alpine means musl instead of glibc and requires a separate build, and multi-arch support for arm64 including Graviton and Apple Silicon dev machines is the usual source of schedule slip. Laravel Vapor requires a custom Lambda runtime rebuild, and shared hosting or PaaS platforms without build hooks are likely blockers because no prebuilt binaries are published.
- Is there a pure-PHP B3 propagator I could use instead?
- Check the SDK and the contrib packages first, because a pure-PHP B3 propagator would let you avoid the native build entirely. Propagation is microseconds of work, so the extension's value is throughput at scale, not capability. If a PHP implementation exists and profiling shows its per-request cost is negligible on your workload, this is an optimization you can defer indefinitely.
- What are the maintenance and supply chain risks?
- Three stand out. You are compiling C in CI, so pin the commit and checksum. The repository is a read-only subtree split with no issue tracker, pull requests, or changelog of its own and effectively zero battle-testing, so you will be an early adopter rather than a follower. If the extension lags an SDK release, your upgrade path is blocked until it catches up.
- How do I verify B3 propagation works end to end?
- Send a request carrying b3 or X-B3-* headers into a route and assert the SDK extracted a valid trace ID and span ID, then assert your outbound HTTP client injects the same context. Repeat with only W3C headers present to confirm the composite propagator still works. Run the same check in CI with the compiled extension loaded, so ABI or build regressions surface before deployment rather than in production.
Weaver
How can I help you explore Laravel packages today?