Elastic Apm Laravel Laravel Package

Technical Evaluation

Architecture fit. arkaitzgarro/elastic-apm-laravel is a thin Laravel service-provider wrapper around Elastic's official elastic/apm-agent-php extension. It fits cleanly into a conventional Laravel architecture: auto-discovery registers the provider, middleware captures HTTP transactions, and the package hooks the framework's events, exceptions, and query builder to emit spans. There is no data-store footprint, no schema, and no queue worker of its own — instrumentation is in-process, which makes it architecturally low-impact but also means it inherits the constraints of the underlying PHP agent (Zend extension, INI configuration, per-process lifecycle under PHP-FPM/Octane).

Integration feasibility. Mechanically straightforward: composer require, publish config, set ELASTIC_APM_* env vars, confirm the agent extension is loaded. v8.0.0 raises the floor to PHP 8.3+ and adds Laravel 13 support while dropping Laravel 11. That makes this a hard gate rather than an additive feature release — v8 is only installable on Laravel 12/13 with PHP 8.3+. Teams on Laravel 11 are pinned to v7.x and receive no further updates.

Technical risk.

• Platform-forced upgrade. The v8 upgrade is not independently shippable; it is chained to a Laravel 11→12/13 and PHP 8.2→8.3 migration. Runtime version is now a hard dependency of observability, which inverts the usual "observability is the last thing to break" expectation.
• Laravel 13 maturity. Support for a newly released major means the compatibility surface is thin. Expect a patch tail (v8.0.x) as edge cases in the framework's event and Octane lifecycle surface are found.
• Agent coupling. Instrumentation depends on the elastic/apm-agent-php extension, whose version compatibility with PHP 8.3/8.4 is a separate constraint from this package's own constraints. Two version matrices must be satisfied simultaneously.
• Bus factor. Single-maintainer community package. Release cadence is responsive but the project is not backed by an SLA; a stalled release can block a framework upgrade.
• Instrumentation overhead. Always-on tracing adds per-request CPU and memory; uninstrumented sampling and collection rates are a production-sizing consideration, not a default.

Key questions.

1. Is Elastic APM a committed part of the observability strategy, or is this a legacy integration being carried forward? (Determines whether to invest in the upgrade or migrate to OpenTelemetry.)
2. What is the current fleet distribution across Laravel 11/12/13 and PHP 8.2/8.3? That directly sizes the work.
3. Does the deployed elastic/apm-agent-php extension version support the target PHP runtime?
4. Are we running Octane/Swoole or RoadRunner? Long-lived workers have different agent lifecycle behavior and need explicit validation.
5. What is the acceptable behavior when the APM server is unreachable — must the app fail open (recommended) and is that configuration audited?
6. Is there a documented exit path to OpenTelemetry if this package's maintenance lags?

Integration Approach

Stack fit. Suitable for standard Laravel HTTP + queue workloads on PHP-FPM. Less proven under Octane/long-lived workers, where the agent's per-process assumptions and span flushing need explicit verification. If the stack is Laravel 12 with PHP 8.3 and Elastic APM is already the standard, v8 is a natural, low-friction fit. If Laravel 13 is not yet adopted, v8 delivers no functional benefit — it only removes supported versions.

Migration path. Two distinct paths:

• From v7 on Laravel 12 / PHP 8.3+: effectively a no-op upgrade — bump the constraint, run the test suite, verify instrumentation still emits transactions and spans, confirm no config keys changed. Low risk.
• From v7 on Laravel 11 or PHP 8.2: blocked. The Laravel and PHP upgrades must land first. Recommended order: PHP 8.3 → Laravel 12 → this package v8 → Laravel 13. Do not attempt to bundle the framework major and the instrumentation major in one change set; a regression during a combined upgrade is difficult to attribute.
• From v6 or earlier: step through v7 first to isolate any intermediate breaking changes, since v8's notes cover only the v7→v8 delta.

Compatibility. v8.0.0 requires PHP ≥ 8.3 and Laravel 12/13 (Laravel 11 dropped). Pin explicitly — "arkaitzgarro/elastic-apm-laravel": "^8.0" plus a PHP platform constraint in composer.json — so CI and production cannot silently diverge. Verify the elastic/apm-agent-php extension version independently; it is not resolved by Composer.

Sequencing.

1. Inventory services by Laravel and PHP version; identify which are blocked.
2. Confirm the APM agent extension supports PHP 8.3 on the target base images and build pipelines.
3. Validate in staging with the APM server reachable and unreachable (failure-mode test).
4. Canary one non-critical service; compare transaction/span volume and error rates against v7 baselines.
5. Roll out service-by-service; keep v7 pins documented for any property that cannot move yet.
6. Schedule a routine revisit on the next Laravel major — this package's support window tracks the framework's, so a repeat of this exercise is expected annually.

Operational Impact

Maintenance. Low day-to-day surface — one Composer dependency, one config file, one set of env vars. The real maintenance burden is the recurring forced-upgrade cadence: each Laravel major triggers a corresponding major here, and each one is a breaking release. Budget this as a standing annual line item, not a one-off. Track the upstream repo for releases; there is no vendor support contract behind it.

Support. Community-supported, single maintainer. No SLA, no escalation path, no guaranteed security patch turnaround. Acceptable for internal observability; a material gap if APM data feeds customer-facing SLAs or billing. Mitigation: keep the abstraction thin (config via env, no deep coupling to package internals) so substitution — including a move to OpenTelemetry — remains a bounded effort.

Scaling. Instrumentation cost scales linearly with request volume, not with cluster size. At high RPS, per-request overhead and span volume become the binding constraints: tune sample rate, transaction sample rate, and span compression; size the APM server and Elasticsearch backing store for ingest, not just for storage. Under horizontal autoscaling, remember every new instance must have the agent extension baked into its image — a missed image variant produces silent blind spots rather than errors.

Failure modes.

• Agent extension absent or not loaded — application runs fine but emits no telemetry; silent, easily mistaken for "no traffic." Needs a startup or synthetic-traffic assertion.
• APM server unreachable — must fail open. Verify the agent's buffering/timeout behavior cannot stall request handling under saturation; this is the highest-severity operational risk and warrants an explicit chaos test.
• PHP runtime mismatch — v8's >=8.3 requirement surfaces as a Composer resolution failure, which is loud and safe. The dangerous variant is a base image still on 8.2 in one environment, producing inconsistent instrumentation across the fleet.
• Long-lived worker span leakage — Octane/Swoole workers that reuse processes can accumulate or misattribute spans if the agent lifecycle is not reset per request.
• Data gaps on upgrade — if service names or environment tags shift during the migration, historical comparisons break; keep service.name and service.environment stable across the cutover.

Ramp-up. A competent Laravel engineer can complete the v8 bump on an already-compliant stack in under a day, most of it verification. The real ramp-up is for whoever owns observability: understanding the agent's INI-level configuration (which lives outside Laravel config), the sampling knobs, and the fail-open behavior. That knowledge is scarce and concentrated — document it, and pair the v8 upgrade with a short runbook covering extension installation, env var reference, and the "no data in APM" triage path.