Opentelemetry Auto Symfony Laravel Package

Technical Evaluation

Architecture fit — this is the headline risk: it is the wrong framework. open-telemetry/opentelemetry-auto-symfony instruments the Symfony HttpKernel / Console / HttpClient stack. Laravel does not use those components for its request lifecycle — it uses Illuminate\Foundation\Http\Kernel, its own console kernel (Illuminate\Console\Kernel), and Guzzle/curl for outbound HTTP. Installing this package in a Laravel application yields, at best, spans for a handful of indirect Symfony contracts (some Laravel internals pull symfony/http-foundation, symfony/console, symfony/process), and, at worst, silently nothing. There is no supported path where this package is the correct production dependency for a Laravel service.

What is genuinely reusable is the pattern, not the package. The OTel PHP auto-instrumentation model is consistent across frameworks:

• A native PECL extension (ext-opentelemetry) provides the hook() / observer API that lets a Composer package instrument userland functions without code changes.
• A Composer auto-instrumentation package ships a _register.php autoload file that registers hooks per framework surface.
• Behaviour is driven almost entirely by OTEL_* environment variables (OTEL_PHP_AUTOLOAD_ENABLED, OTEL_TRACES_EXPORTER, OTEL_EXPORTER_OTLP_ENDPOINT, sampler and propagator settings).
• Export is OTLP to a Collector; backend choice is decoupled.

That architecture is a good fit for our platform. The Symfony package is a reference implementation of it, and a useful one to read when evaluating how much span coverage we get "for free" versus how much requires custom middleware.

Integration feasibility for this specific package: low. For a Laravel estate we would substitute open-telemetry/opentelemetry-auto-laravel (same maintainer group, same extension dependency) or go framework-agnostic with the PDO / Guzzle / curl instrumentation packages plus a hand-written middleware. The Symfony package contributes nothing we cannot get from those.

Technical risk signals are weak across the board:

Additional structural risks: the package is only useful in combination with a compiled PHP extension, which means our container images, CI runners, and local dev environments all need that extension built and version-matched to PHP. That is a platform-level change, not a composer require.

Key questions to resolve before committing engineering time:

1. Confirm the repository's archived status and the canonical replacement path in open-telemetry/opentelemetry-php-contrib. If it is archived, we should not cite it as a dependency anywhere in our architecture.
2. Which Laravel and PHP versions does the Laravel-equivalent package support, and is it on a maintained release cadence or equally stale?
3. Do we actually need auto-instrumentation, or does a thin Laravel middleware plus the framework-agnostic PDO/HTTP packages cover 80% of our trace value at a fraction of the operational cost?
4. Is there an approved vendor path (Datadog, New Relic, Elastic APM PHP agents) that removes the native-extension build burden? Cost and lock-in trade-offs belong in that comparison.
5. What is our span coverage requirement by surface — HTTP inbound, DB, cache, queue jobs, outbound HTTP, console/scheduler?

Integration Approach

Stack fit. Target Laravel 10/11/12 on PHP 8.2+, OTLP over gRPC or HTTP to an OpenTelemetry Collector, Collector fanning out to our backend of choice. The pieces are:

• ext-opentelemetry installed via PECL in the base image, pinned and built in CI.
• open-otemetry/opentelemetry-auto-laravel (verify exact package name and current version) for request/console/queue spans.
• open-telemetry/opentelemetry-auto-pdo, ...-auto-guzzle, ...-auto-curl for dependency spans — these carry most of the diagnostic value regardless of framework.
• The core SDK (open-telemetry/sdk, open-telemetry/exporter-otlp) as the transitive foundation.

Migration path. Do not attempt a Symfony-package pilot. Sequence instead:

1. Spike (1–2 weeks, one engineer). Build a Docker image with the extension, install the Laravel auto-instrumentation package, point at a local Collector + Jaeger, and measure span coverage and request overhead on a representative service. Output: a go/no-go with numbers.
2. Reference implementation. One non-critical internal service end-to-end: traces to Collector, Collector to backend, dashboards for latency and error rate, documented runbook.
3. Platform template. Bake extension + packages + env defaults into the shared base image and a published .env.example. Instrumentation should be a config toggle, not a per-team project.
4. Fleet rollout in risk order, gated on per-service overhead benchmarks.

Compatibility considerations to nail down early:

• Composer allow-plugins entries — the instrumentation packages install via the Composer plugin mechanism and will be blocked by default on Composer 2.2+.
• OTEL_PHP_AUTOLOAD_ENABLED=true must be set, or nothing instruments and there is no error. This is the single most common misconfiguration.
• Alpine/musl images: extension compilation is frequently painful; prefer -slim Debian bases.
• Octane/Swoole and long-running queue workers: context lifecycle and memory behaviour differ materially from FPM; validate separately.
• OpenTelemetry semantic convention version drift between SDK, auto-instrumentation packages, and backend ingestion.

Sequencing note. The Symfony package's only legitimate role in this plan is as a reading reference during the spike — to understand hook registration and span naming conventions. It should not appear in a composer.json.

Operational Impact

Maintenance. The [READONLY] marker implies the package is frozen; any fork we rely on becomes ours to maintain. Budget for tracking the contrib monorepo releases and for re-pinning the PECL extension on every PHP minor upgrade. Treat the instrumentation layer as platform-owned infrastructure with a named owner, not as an application dependency each team manages independently.

Support. Community-only, no SLA, low bus factor evidenced by 58 stars and 0 dependents. Escalation path for a production tracing outage is GitHub issues. If tracing becomes load-bearing for incident response or SLO reporting, that is an unacceptable support posture and argues for a commercial agent or for accepting degraded visibility during instrumentation bugs.

Scaling. Overhead is per-request hook dispatch plus span allocation and export. Expect low single-digit percent latency impact at moderate sampling, but the variance is what bites: export must be batched and non-blocking, and the Collector — not the PHP process — should own tail sampling and backpressure. Watch cardinality on span attributes (user IDs, URLs with path parameters) as the primary cost driver with most backends. Queue workers are the dangerous surface: high-throughput workers generate span volume disproportionate to request traffic.

Failure modes to design for:

• Silent no-op. Extension missing or autoload flag unset → zero traces, no warning. Mitigate with a synthetic canary trace emitted on deploy and an alert on trace absence.
• Exporter backpressure. Collector or backend unreachable → batched spans buffer in memory. Bound the queue and drop, never block the request path.
• Partial coverage illusion. Traces exist for HTTP but not for DB or queue jobs; teams then draw wrong conclusions from incomplete waterfalls. Publish a coverage matrix rather than a "tracing is on" statement.
• Context propagation gaps. Async jobs, scheduled commands, and outbound calls to non-instrumented services break the trace tree. Manual traceparent injection is required at those seams.
• Extension/PHP upgrade breakage. A PHP minor bump without a matching PECL build blocks deploys entirely — this is a CI-gating dependency, not a runtime nicety.

Ramp-up. Roughly one to two engineer-weeks to get the first service instrumented and readable, plus meaningful enablement cost across teams: how to read a waterfall, how sampling interacts with debugging, how to add manual spans for domain-specific operations, and a cost-governance conversation with whoever owns the observability budget. The tooling is the easy part; the change in debugging practice is where adoption succeeds or stalls.

Recommendation. Do not adopt open-telemetry/opentelemetry-auto-symfony. Use it as a design reference only. Evaluate the Laravel-equivalent auto-instrumentation package plus framework-agnostic PDO/HTTP packages against a commercial APM agent on three axes — native-extension build burden, span coverage for queues and DB, and support posture — and make the decision after the two-week spike, not before.