- How do I install arkaitzgarro/elastic-apm-laravel in a Laravel application?
- Run composer require arkaitzgarro/elastic-apm-laravel, then make sure Elastic's elastic/apm-agent-php Zend extension is installed and loaded in your PHP runtime, since this package only wraps it. Publish the package config with artisan vendor:publish if you want to customise defaults, and set the ELASTIC_APM_* environment variables such as service name and server URL. The service provider is auto-discovered, so no manual registration is needed. Finally, hit an endpoint and confirm transactions appear in Kibana APM.
- Which Laravel and PHP versions does elastic-apm-laravel support?
- Version 8.x requires PHP 8.3 or newer and supports Laravel 12 and 13, while dropping Laravel 11. If you are still on Laravel 11 or PHP 8.2 you must stay on the 7.x line, which no longer receives updates. Treat the v8 constraint as a hard gate tied to your framework and runtime upgrade rather than an optional feature bump.
- Do I need the elastic/apm-agent-php extension to use this package?
- Yes. This package is a thin Laravel service provider around Elastic's official elastic/apm-agent-php extension, which performs the actual instrumentation at the PHP level. You need to install and enable that Zend extension in php.ini and verify it is loaded before any transactions will be reported. That also means you have two version matrices to satisfy simultaneously: the extension's PHP compatibility and the package's Laravel compatibility.
- How do I configure the APM server URL and service name?
- Configuration is driven by ELASTIC_APM_* environment variables read by the underlying agent, for example ELASTIC_APM_SERVER_URL, ELASTIC_APM_SERVICE_NAME, ELASTIC_APM_SECRET_TOKEN, and ELASTIC_APM_ENABLED. You can publish the package config file to adjust defaults, but the agent's INI and environment settings ultimately control behaviour. Keep these values out of version control and set them per environment.
- Does elastic-apm-laravel automatically trace database queries and queued jobs?
- Yes. The package hooks Laravel's query builder, events, and exception handler to emit spans for database queries, HTTP requests, and background jobs without manual instrumentation in most cases. Each HTTP request becomes a transaction with child spans covering the work it performs. You can add custom spans around your own code where the automatic tracing is too coarse.
- What happens if the Elastic APM server is unreachable?
- The agent is designed to fail open, so if the APM server cannot be reached your application keeps serving requests and trace data is dropped or buffered. You should still confirm this explicitly in staging by pointing the agent at a dead endpoint and exercising key paths. Review timeouts and buffer settings so an unreachable collector never becomes a latency source.
- Is elastic-apm-laravel compatible with Laravel Octane, Swoole, or RoadRunner?
- Standard PHP-FPM workloads are the best-supported path. Long-lived workers such as Octane, Swoole, and RoadRunner change the agent's per-process lifecycle assumptions, so span flushing and transaction boundaries need explicit verification. Test under load with your actual worker setup before rolling out to production.
- How do I upgrade from v7 to v8 of elastic-apm-laravel?
- From v7 on Laravel 12 and PHP 8.3 or newer, the upgrade is effectively a no-op: bump the constraint, run your test suite, and verify transactions and spans still arrive. From Laravel 11 or PHP 8.2 you are blocked and should upgrade in stages: PHP 8.3, then Laravel 12, then this package, then Laravel 13. Avoid bundling the framework major and the instrumentation major into a single change set.
- What is the performance overhead of running this APM agent in production?
- Always-on tracing adds per-request CPU and memory cost, plus network traffic to the APM server. The overhead is usually small but must be sized deliberately: set sampling rates and collection limits rather than relying on defaults. Benchmark in a representative environment before enabling it across the whole fleet.
- Should I use this package or migrate to OpenTelemetry for Laravel APM?
- If Elastic APM is already your standard and you are on Laravel 12 with PHP 8.3, this package is a natural low-friction fit. Keep in mind it is a single-maintainer community project with no SLA, so a stalled release can block a framework upgrade. If your observability strategy is in flux, plan an exit path to OpenTelemetry before that maintenance gap becomes urgent.