Opentelemetry Auto Laravel Laravel Package

Product Decisions This Supports

• Observability strategy: instrument once, route anywhere. The package auto-instruments Laravel's HTTP kernel, routes, middleware, DB queries, queue workers, HTTP client calls, and console commands against the OpenTelemetry API, emitting traces to any OTLP-compatible backend (Jaeger, Tempo, Honeycomb, Datadog, New Relic). The decision it unlocks is decoupling instrumentation from vendor — you can change APM vendors or backends without a re-instrumentation project. That is a durable architectural commitment, not a one-off tooling purchase.
• Build vs. buy for telemetry. It moves the "build" option from write custom middleware, query listeners, and queue hooks to adopt a contrib package and configure an exporter. Materially less engineering investment, and the same asset is reusable across every Laravel service in the portfolio.
• SLO/error-budget and on-call maturity roadmap. Request-level traces with child DB and queue spans make it feasible to define latency SLOs per endpoint, separate application time from query time and worker time, and cut mean-time-to-diagnosis. Whether you invest in on-call maturity this quarter is a decision this data supports.
• Release and rollout gating. Per-route latency percentiles and span-level error rates enable canary analysis and progressive delivery decisions (promote vs. roll back) instead of relying on aggregate 5xx counts.
• Queue and worker reliability investment. Async job duration, failures, and retries are a classic Laravel blind spot; visible job spans tell you whether to prioritize queue hardening, Horizon tuning, or worker capacity.
• Prioritization signal for platform/performance work. Query-level spans surface N+1 patterns and slow-query hot spots, converting anecdote-driven performance tickets into evidence-backed roadmap items.
• Monolith decomposition decisions. If you are splitting a monolith into Laravel services, consistent trace propagation across service boundaries is a gating capability. Adopting it before the split de-risks the decomposition.
• Cost/scope control as a product input. Sampling ratios, per-environment exporters (console locally, OTLP + batch + ratio sampling in production), and collector-side filtering of health checks mean telemetry volume — and therefore observability spend — is a tunable lever rather than a runaway line item.

When to Consider This Package

Consider adoption when most of the following hold:

• You already run, or are committed to standing up, an OpenTelemetry Collector and an OTLP backend. Without a consumer, this package emits spans nobody reads.
• You are on a currently supported Laravel version and PHP 8.1+, and can pin both the package and the native opentelemetry PHP extension in your base image (php-fpm pool, systemd unit, or container env — not .env, which is read too late).
• You need vendor-neutral, portable instrumentation across several Laravel services, or you are deliberately avoiding deep APM agent lock-in.
• You have engineering capacity to own the integration: validating span quality, tuning sampling, maintaining collector config, and absorbing breaking changes from a contrib-tier dependency. The package's own failure mode is silent — no extension or a bad vendor/ glob yields zero spans and zero errors — so someone must own "is the pipeline actually working?" verification.
• The blast radius is containable: start with one non-critical service, behind a flag, with a documented rollback to no instrumentation.
• You want framework-aware spans out of the box rather than hand-rolling middleware and query listeners.

Look elsewhere when:

• You need turnkey APM with vendor support and SLAs. A commercial agent (Datadog, New Relic, Sentry) or Laravel Nightwatch will reach value faster and carries contractual support.
• You have no OTel infrastructure and no appetite to operate a collector. The true total cost of ownership here is the collector and backend, not this package; adopting the package without them is a science project.
• Your Laravel or PHP versions sit outside the supported matrix, or you cannot add a PHP extension to the runtime (shared hosting, constrained PaaS). Note also that it must not be a require-dev dependency — composer install --no-dev in production silently removes all tracing.
• You need profiling or product analytics rather than tracing. Blackfire, Telescope, and event pipelines solve different problems; don't force this package into that role.
• The organization requires audited, well-adopted dependencies. With ~63 stars and zero dependents, this is early-adopter territory, not a safe default for a platform standard.
• You run Octane or long-lived workers and are unwilling to own the additional integration work: the SDK's auto-shutdown doesn't flush where you'd expect, spans can go unended, and request state can bleed across workers. This is solvable (build the SDK with auto-shutdown disabled and flush explicitly) but it is a real engineering task, not configuration.

Price in the core risk: low adoption means you will be the one finding the edge cases. Version-matrix drift after Laravel upgrades is the single most likely way this breaks for you, since the auto-instrumentation hooks target internal framework methods whose signatures change. Plan for a post-upgrade check (composer why-not, plus verifying hook targets still exist) as standing maintenance.

How to Pitch It (Stakeholders)

For executives: This is a low-cost, standards-based way to make our Laravel services observable — request latency, database time, and background job health — without buying a proprietary agent or committing to a single monitoring vendor. It is an enabler for SLOs, faster incident resolution, and safer releases; it is not a customer-visible feature and should not be sold as one. The strategic value is optionality: standardizing on OpenTelemetry means a future vendor change is a configuration change, not a re-instrumentation project. Recommend a time-boxed pilot on one internal, non-critical service with explicit success criteria — spans flowing end to end, useful latency breakdowns, no measurable performance regression, and a working kill switch — before any platform-wide commitment.

For engineering: OpenTelemetry's Laravel auto-instrumentation gives us framework-aware spans — HTTP, routes, middleware, queries, queues, HTTP clients, console — with near-zero custom code, and keeps us portable across backends. Practical caveats to plan around: it requires the native opentelemetry PHP extension loaded at process start; configuration must live in real environment variables, not .env; failures are silent, so verify with the console exporter before debugging anything else. We enrich spans at the edges (a global middleware for user/tenant attributes) rather than replacing the framework spans, and we write our own custom spans via Globals::getTracer() so business logic stays decoupled from the instrumentation library. Budget roughly 1–2 engineer-weeks for the pilot, mostly collector setup, sampling policy, queue trace-context propagation, and verifying span quality — plus a small recurring maintenance cost after each Laravel upgrade.

For security/compliance and data owners: Traces can capture route parameters, full SQL statements, and URLs containing identifiers. We will define redaction and cardinality policy up front at the collector (attribute processors, tail sampling) rather than patching vendor code, and we will explicitly confirm whether db.statement capture is enabled in our pinned version before enabling it in production.