Opentelemetry Bundle Laravel Package

Technical Evaluation

Architecture fit. friendsofopentelemetry/opentelemetry-bundle remains a Symfony bundle, not a Laravel package — still the single most important finding, and unaffected by beta.7. It wraps the framework-agnostic open-telemetry/opentelemetry-php SDK and adds Symfony-specific glue: DI compiler passes, auto-instrumentation decorators for the HTTP kernel, PSR-18/HttpClient, Messenger, Console, Doctrine, and Twig, plus config-tree handling for exporters, samplers, and resource attributes. The portable value sits in the SDK and opentelemetry-php-contrib instrumentation, not in the bundle. For a Laravel codebase there is no boot path: Laravel's service provider lifecycle never registers a Symfony bundle, and Laravel's use of Symfony components (HttpFoundation, Console, VarDumper) does not supply a Kernel for the bundle to hook.

Integration feasibility. High for Symfony 6.4/7.x on PHP 8.1+. Low-to-zero for Laravel as-is. The realistic Laravel path is unchanged: consume the SDK plus contrib instrumentation and write a thin ServiceProvider + middleware ourselves — borrow the bundle's pattern, not the dependency. A design task, not an install task.

What beta.7 changes. The release is narrow and mostly hygiene, with one substantive feature:

• Messenger worker + middleware instrumentation (PR #173, first-time contributor). This is the first release to address async context propagation inside the bundle itself — previously the weakest link in our assessment. It is also the highest-risk surface to introduce: long-running worker instrumentation is exactly where span accumulation, memory growth, and orphaned traces bite. It is brand new, has no field history, and covers Symfony Messenger only — it does nothing for Laravel's queue abstraction.
• PHPUnit ^13 upgrade to clear security advisories (PR #216). Dev-tooling only; no runtime impact, but a positive signal that the maintainer is tracking advisories.
• Dependabot bumps to CI actions (upload-artifact, setup-php, cache, setup-node). Build hygiene, not product capability.

Technical risk.

• Pre-1.0 status persists: beta.7 is the seventh beta of v1.0.0. No stable API contract, no documented BC guarantees. Every pin is provisional.
• Adoption risk: still ~68 stars, effectively 0 dependents, maintainer pool 1–2. The new contributor is a good sign but does not change the bus factor. No unproven-quality signal; a clear unproven-operational-history signal.
• Version churn: the OTel PHP SDK and contrib instrumentation have moved through breaking majors; pin the bundle, SDK, and contrib together, never float.
• New-code risk in async paths: the Messenger instrumentation is one release old and directly touches the failure mode we care most about (worker lifetime, span leakage, propagation across serialized messages). Treat it as unvalidated until we test it ourselves.
• Silent breakage: auto-instrumentation decorates framework internals. A minor Symfony bump can break a decorator with no failure on our side — telemetry simply goes dark. The new Messenger decorators broaden this surface.
• Config drift: if the bundle's config tree diverges from the OTEL_* env-var spec, our platform-level collector/sampling config stops being the source of truth.
• Release metadata: the previously noted 2026-04-28 last-release date should still be sanity-checked against actual tags before we treat cadence as healthy.

Key questions.

1. Is the target application actually Symfony, or is "Laravel/PHP" the assumed stack? This determines whether we evaluate or reject.
2. For Laravel: what is the maintained alternative (keepsuit/laravel-opentelemetry, contrib packages, or in-house)? Which has a healthier release cadence — and is there a Laravel-native equivalent of the new Messenger instrumentation?
3. Does the bundle honor the OTEL_* spec (endpoint, sampler, resource attributes) or require proprietary config?
4. What is the CI matrix (Symfony versions × PHP versions) and is there a documented upgrade path across SDK majors?
5. Now partially answerable: does the new Messenger worker/middleware instrumentation propagate context across queue producers/consumers correctly, and does it bound span growth in long-lived workers? What is the required Messenger version, and is there a documented migration for apps already hand-rolling this?
6. What is measured per-request overhead with the batch span processor and default sampling — and, newly relevant, per-message overhead in a consumer loop?

Integration Approach

Stack fit. Strong for Symfony + Doctrine + Messenger + PSR-3/PSR-18, and improved by beta.7: async propagation is now first-class for Messenger rather than something we hand-roll. For Laravel the fit is still indirect — Laravel speaks PSR-3 and PSR-18, its HTTP client and queue are wrappable, so the SDK fits and the bundle does not. Treat the bundle as a reference implementation, and now specifically as the reference for how to do queue instrumentation, even though the code will not transfer.

Migration path.

• If Symfony: composer require, register in bundles.php, point the OTLP exporter at the collector, set resource attributes (service.name, deployment.environment, version), then enable instrumentation one decorator at a time. Enable Messenger instrumentation last and separately — it is the newest code and the hardest to validate.
• If Laravel: time-boxed POC on the SDK + contrib directly; implement a ServiceProvider, a middleware that starts/ends the root span and injects trace context, and queue-job propagation via serialized headers. Budget 1–2 sprints for a senior engineer, unchanged.

Compatibility. Pin exact versions of bundle (beta.7), SDK, and contrib instrumentation together. Verify the Messenger instrumentation against the exact Symfony Messenger version we deploy — new decorators commonly assume a specific middleware-priority arrangement. Validate against the collector version and the backend's OTLP support (HTTP vs gRPC). Confirm behavior on the PHP version we actually run, not just the CI floor.

Sequencing (gate each phase on measured overhead and trace continuity in the backend).

1. Stand up collector + backend; agree on resource attribute schema.
2. SDK baseline + sampling policy (head-based at SDK, tail-based at collector).
3. Traces on the inbound request path only.
4. Outbound HTTP and DB spans.
5. Console commands.
6. Async queue producers/consumers — via the bundle's new Messenger instrumentation if Symfony, hand-rolled if Laravel. Include a soak test on a long-lived worker.
7. Metrics, then log correlation via trace/span IDs.

Operational Impact

Maintenance. Upstream is small and community-run; if we fork or vendor, we own it. Recurring cost is the dependency-upgrade treadmill: every Symfony minor and every OTel SDK major is a validation exercise. Beta.7 slightly reduces effort on the async path (we would have written that instrumentation anyway for Symfony) but adds a dependency on beta-grade code in a production-critical path. Keep the instrumentation surface minimal and prefer contrib packages over hand-rolled decorators.

Support. MIT, no vendor SLA, thin issue triage at ~68 stars. A first-time contributor landing a substantial feature is encouraging for bus factor but also means the least-reviewed code lands in our riskiest area. Requires a named internal owner and a documented "telemetry is degraded, here's the runbook" path. Do not make this a blocking dependency for incident response.

Scaling. Levers remain the batch span processor and the sampler. Beta.7 raises the stakes on the worker-lifetime failure mode: span accumulation in process-lifetime Messenger consumers is now the bundle's code path, not just ours. Enforce span limits, periodic worker recycling, and memory alerting on consumers. Sampling decisions must be consistent across services or traces fragment.

Failure modes.

• Exporter on the request path → added latency and timeouts. Must batch asynchronously and fail open; telemetry must never fail a user request.
• Collector unavailable → drop spans silently, alert on exporter drop counters, never queue unboundedly.
• Missing/incorrect sampler config → either no data during incidents or cost blowout.
• Double instrumentation (bundle auto-instrumentation + pre-existing hand-rolled queue spans) → inflated or duplicated spans. Relevant now: apps that already propagate context manually through Messenger must disable one or the other.
• Broken context propagation in async paths → orphaned traces that look like outages. Newly a bundle-owned bug surface as of beta.7.
• Worker memory growth from unbounded span accumulation in the new Messenger instrumentation.
• Silent decorator breakage on framework upgrade → dashboards look healthy while data is absent. Add a synthetic trace check to CI or staging, including one synthetic queued message so the new path is covered.

Ramp-up. The team needs OpenTelemetry concepts — spans, context propagation, resources, samplers, exporters — plus (newly) enough Symfony Messenger knowledge to reason about middleware ordering and worker lifecycle. Estimate 1–2 weeks for a senior engineer plus the POC sprint; add roughly 2–3 days if we intend to validate and adopt the new Messenger instrumentation.

Recommendation. Beta.7 is a useful but incremental release: it materially strengthens the Symfony case for async workloads and shows healthy maintenance signals (new contributor, advisory hygiene), but it does not change the core finding for a Laravel target, and it introduces fresh, unproven code into the highest-risk operational path. Hold the prior positioning: pattern reference for a Laravel stack; candidate dependency for a confirmed Symfony stack — now pending a spike that explicitly soak-tests the Messenger worker instrumentation before adoption.