Laravel Opentelemetry Laravel Package

Technical Evaluation

Architecture fit. This package is a Laravel service provider that instruments framework-level seams — HTTP kernel, Eloquent/DB, queues, console commands, cache/Redis, and the Guzzle HTTP client — and emits OpenTelemetry spans through the upstream OTel PHP SDK. For a TPM, the key point is that instrumentation is owned by the framework integration rather than smeared across application code, and the output wire format is OTLP, not a vendor agent protocol. That means the instrumentation decision and the backend decision are decoupled: we can adopt tracing now and defer (or reverse) the vendor choice later. It fits a Laravel monolith or a modest service fleet well. It fits poorly if we already run a vendor SDK with its own auto-instrumentation, because we would be operating two overlapping instrumentation layers.

Integration feasibility. The code-level integration is small: a Composer dependency, a published config file, and OTEL_* environment variables. The real cost is infrastructure and convention — an OTel Collector tier, service naming, resource attributes, sampling policy, and a redaction policy. A credible pilot in one non-critical service is a one-sprint exercise; a production-grade rollout with collector operations is four to six weeks. License is MIT and the dependency footprint is small, so procurement and legal friction are near zero.

Technical risk.

• Weak adoption signal. ~190 stars and zero Packagist dependents means effectively no downstream production validation; we would be an early adopter absorbing discovery cost. Release 2.2.7 is illustrative: a patch-level fix made HTTP client traces finally record failed outbound requests — a mainstream failure path was under-instrumented until a recent patch. Expect more of these.
• Bus factor. Effectively single-maintainer. Only viable with a fork-and-vendor contingency and a named internal owner.
• Upstream churn. The OTel PHP SDK and semantic conventions are still moving; pinning the package and SDK together and testing upgrades as a unit is mandatory.
• Coverage gaps. Auto-instrumentation won't span domain logic (pricing, orchestration, saga flows). Manual spans become a developer-experience and training obligation, not a nice-to-have.
• Data governance. SQL text, bindings, URLs, and headers can leak PII or secrets into span attributes. A redaction policy has to exist before production, not after the first audit finding.
• Performance. Per-request overhead is modest but real; a synchronous exporter is the classic mistake and will add tail latency precisely when the collector tier is degraded.

Assessment of 2.2.7. One bug fix, no breaking changes, no config surface change — so the integration plan and migration path don't move. But it matters more than the diff size implies. Failed outbound calls are the spans that drive MTTR and error-rate SLOs; a gap there means trace-derived error rates understate reality, and any parallel-run comparison against an incumbent APM during the pilot would have flattered this package. Two consequences: set a minimum version of 2.2.7 for any pilot so we aren't evaluating a known-defective baseline; and treat any traces collected on ≤2.2.6 as unreliable for outbound error analysis.

Key questions for the team.

1. What is our exit cost if the maintainer walks away — does the OTel-standard API make replacement a config change or a rewrite?
2. Do we have (or will we fund) a Collector tier, and who owns it?
3. What is our sampling policy — head-based at the SDK, tail-based at the Collector, or both?
4. Which incumbent APM/logging vendor are we displacing, and what is the parallel-run window? (Baseline it on ≥2.2.7.)
5. Are runtime constraints satisfied — PHP extension availability in build images, Octane/Swoole long-lived worker behaviour, container base images?
6. Who signs off on span-attribute redaction and retention?
7. What is our minimum-version policy for this package, and who reads the changelog before we bump?

Integration Approach

Stack fit. Targets modern Laravel (10/11/12) on PHP 8.1+, and composes with the usual suspects: Monolog for log correlation, Guzzle for outbound calls, Redis/SQS/database queues, Eloquent. Because the wire format is OTLP, the same instrumentation feeds Grafana Tempo/Loki/Mimir, Jaeger, Datadog, New Relic, or Honeycomb. Instrumentation stays vendor-neutral and the backend becomes a procurement decision rather than an engineering one — the single strongest argument for this package over a vendor agent. None of this is affected by 2.2.7.

Migration path. Treat the Collector as the architectural boundary from day one: application → OTLP → Collector → backend. Every later change — backend swap, sampling policy, attribute scrubbing — becomes a Collector config change with no redeploy. Pilot in one non-critical service in staging, then production, and run in parallel with the incumbent APM for a quarter. Compare trace completeness, MTTR on real incidents, and cost per span before committing to decommission. Pin the pilot floor at 2.2.7 so outbound failures appear on both sides of the comparison.

Compatibility checks. Pin package and OTel SDK together; upgrade and test as a unit. Verify PHP extension availability in build images (native extension is faster but operationally awkward; pure-PHP is simpler but slower). Validate behaviour under Octane — long-lived workers change how batch buffers and memory behave. Confirm OTEL_* env vars don't collide with existing platform config and that queue workers flush spans on graceful shutdown. Add one acceptance criterion the previous plan missed: after any bump, assert that error paths still emit spans — 2.2.7 is a reminder that coverage can arrive late, at patch level, without ceremony.

Sequencing.

1. ADR covering vendor-neutrality goal, Collector ownership, and data-handling policy.
2. Stand up the Collector in staging; select backend and sampling defaults.
3. Pilot one service on ≥2.2.7, traces only, with manual spans for the two or three highest-value business transactions.
4. Publish conventions: service naming, resource attributes, span naming, redaction rules, sampling tiers.
5. Extend to queues, scheduled jobs, and external HTTP; verify context propagation across async boundaries explicitly, and include a deliberately failing outbound call in the acceptance test.
6. Add metrics and log correlation; build SLO dashboards and burn-rate alerts on the new signals.
7. Roll out fleet-wide and retire the legacy agent, with a documented rollback.

Operational Impact

Maintenance. Low steady-state code maintenance, non-trivial dependency maintenance. Budget recurring effort for Renovate-driven upgrades, upstream SDK changelog review, and a quarterly compatibility test against the newest Laravel major. Keep a fork or vendored config overlay so a stalled upstream is an inconvenience rather than an outage. Read patch releases, not just minors — 2.2.7 changes what is visible in production and would have been easy to skip as "just a patch."

Support. No commercial support. Reliance is on GitHub issues and maintainer goodwill, which is not an acceptable primary support model for a tier-1 service. Mitigate by naming an internal owning team (platform/observability), writing an internal runbook, and pre-agreeing the fallback: replace the package with direct OTel SDK instrumentation — a bounded effort precisely because the API surface is standard.

Scaling. The Collector scales horizontally and independently of the application, which is the right decoupling. Cost control lives in sampling: tail-based sampling at the Collector keeps all spans for errors and slow requests while discarding the boring majority. Watch exporter backpressure, agent CPU (typically low single-digit percent), and metric cardinality — user IDs or raw URLs as metric labels will destroy a metrics backend faster than volume will. Note 2.2.7 slightly increases span volume on the error path; negligible in most cases, but retune sampling thresholds if outbound failure rates are high.

Failure modes and mitigations.

• Collector unavailable → spans dropped. Ensure the exporter is asynchronous and non-blocking with short timeouts; telemetry loss must never become request latency or a 5xx.
• Queue workers terminated without flush → truncated traces. Hook the shutdown path and verify with a synthetic job.
• Context lost across async boundaries → orphaned traces that look like slow dependencies. Add explicit propagation tests for every queue and scheduled-job path.
• Unredacted attributes → PII leaking to a third-party backend. Collector-side scrubbing plus SDK-side limits, reviewed before production.
• Upstream breakage on a minor bump → instrumentation silently stops. Automated smoke test that asserts trace emission after every dependency update.

Ramp-up. Expect one engineer to reach productive use in a week and the team to be fluent in manual span authoring and trace-based debugging in four to six weeks, gated on two enablers: published conventions (naming, attributes, redaction) and at least one worked example of a business transaction traced end-to-end. TPM-owned deliverables during ramp-up are concrete: the ADR, the success criteria for the pilot (trace completeness, overhead, MTTR delta, cost per span), the named owning team, and a documented rollback to commercial APM. Without those, the technical work will succeed and the organizational adoption will stall.