Laravel Otel Laravel Package

Product Decisions This Supports

• Observability vendor strategy / build-vs-buy. laravel-otel is an OpenTelemetry instrumentation layer for Laravel, so it decouples "what telemetry we emit" from "who stores and displays it." That makes the real decision the backend (Grafana/Tempo, Honeycomb, Datadog, New Relic, an internal collector), which can be trialed, swapped, or dual-shipped without re-instrumenting the app. Instrumentation becomes a one-time cost instead of a per-vendor migration.
• Roadmap input: reliability and incident-response work. Traces across HTTP requests, DB queries, queue jobs, and scheduled tasks are what let you answer "why was checkout slow at 14:02" without adding ad-hoc logging. This package is a cheap enabler for SLOs, error-budget reporting, and on-call runbooks — features that are hard to justify retroactively but easy to scope once tracing exists.
• Prioritizing the "invisible work" backlog. Laravel's scheduler and queue workers are classic blind spots (nobody notices a silently failing nightly job until a customer does). The v0.4.2 patch specifically fixes ScheduleWatcherOptions, i.e. the configuration surface for scheduled-task tracing — a signal that this exact gap is being actively worked, and a reason to include "scheduled job visibility" as a near-term deliverable rather than a someday item.
• Use cases worth scoping now: latency triage on customer-facing endpoints, slow-query attribution after a release, queue backlog and job-failure forensics, and per-tenant/per-customer latency breakdowns (via span attributes) for enterprise accounts asking "is it us or you?"
• Deployment-model decisions. Because telemetry is emitted via an open standard, you can keep data in your own VPC (compliance-sensitive customers) rather than shipping traces to a third party — a decision that often unlocks regulated or enterprise deals.
• Platform-team leverage. One instrumentation package serves every Laravel service, so the marginal cost of onboarding the tenth service is near zero. That's an argument for standardizing now rather than letting each squad pick its own APM.

When to Consider This Package

Adopt when:

• You run Laravel 10/11 (verify the package's supported matrix against your version before committing) and already have, or are actively selecting, an OTel-compatible backend. Instrumentation without a collector destination is shelfware.
• You want vendor-neutral telemetry and are uncomfortable with per-host APM licensing that scales with instance count.
• You have a platform/infra engineer who can own the collector pipeline; the package covers the app side, not the operations side.
• Your pain is breadth — you need reasonable coverage across HTTP, queries, queues, and scheduler quickly — rather than deep profiling of a single hot path.
• You're willing to treat it as a pre-1.0 dependency: pin the version, wrap configuration in your own config layer, and accept that minor releases may shift behavior.

Look elsewhere or defer when:

• You need vendor support, an SLA, or a security questionnaire answered. This is a pre-1.0, effectively single-maintainer package. That's a real risk for a revenue-critical path, and v0.4.2 being a one-line fix is a reminder of the release cadence: small, frequent, low-ceremony — good for responsiveness, thin on formal change management.
• You need deep performance profiling (flame graphs, allocation-level analysis). Blackfire or Tideways answer a different question than tracing does.
• You want zero operational overhead. A fully managed agent (Datadog's PHP tracer, New Relic) trades lock-in and cost for someone else owning the pipeline and the upgrade path.
• Your stack is heterogeneous and mostly non-PHP. Choose instrumentation per language, but pick the backend once — don't let this package drive a backend decision it can't serve.
• You can't yet answer "who looks at the traces?" Tracing without a dashboard owner and an alerting story produces cost and no behavior change. Solve the ownership question first.

Risk notes to carry into the decision: pre-1.0 versioning (0.x) means no compatibility promise; bus-factor of one maintainer argues for a fork-and-vendor contingency or at least a documented fallback to manual OTel SDK instrumentation; and instrumentation overhead should be measured on your own hot paths, not assumed from benchmarks.

How to Pitch It (Stakeholders)

For executives (one paragraph): We can add production tracing to our Laravel services using an open-source, open-standard integration instead of buying a proprietary agent. That means we pay for the observability backend we choose — and can change that choice later without re-instrumenting the application. The business outcome is faster incident diagnosis ("why is checkout slow") and visibility into background jobs that currently fail silently. The cost is a small, time-boxed engineering effort plus ongoing ownership by the platform team. The main caveat is maturity: this is a pre-1.0 package with essentially one maintainer, so we should pin the version, keep our configuration in our own code, and treat the fallback (manual OpenTelemetry instrumentation) as a documented plan B rather than an emergency.

For engineering (the honest version): This is a thin, config-driven instrumentation layer — you'll get spans for requests, queries, queues, and the scheduler without hand-writing middleware everywhere. The v0.4.2 release is a targeted fix to ScheduleWatcherOptions, which is the knob for scheduled-task tracing; if scheduler visibility is on your list, this release is the one that makes that configuration behave. Two things to internalize before you adopt: (1) 0.x means minor bumps can move behavior — pin it and read changelogs on upgrade; (2) it does not include the collector or backend, so budget for that pipeline and its owner explicitly. Recommendation: time-box a spike on one non-critical service, measure overhead against our p95 latency budget, confirm the data is actionable in the backend, and only then standardize across services.