Elastic Apm Symfony Bundle Laravel Package

Getting Started

• Reality check first: mmft24/elastic-apm-symfony-bundle is a Symfony bundle, not a Laravel package. There is no service provider, facade, or package auto-discovery. v2.0.0 is a ground-up refactor delivered in a single PR by a first-time contributor, so treat it as a new package — do not assume 1.x namespaces, config keys, or service IDs survived.
• Prerequisites before touching the bundle: the Elastic APM PHP agent extension must be installed and loaded (php -m | grep -i apm), with elastic_apm.enabled=1, a service_name, and a reachable APM Server. If the agent isn't reporting at the PHP level, the bundle cannot help you.
• Where to look first: read the bundle class, the DI Extension/Configuration classes, and the event subscriber/listener directory in src/. Those three tell you (a) what config tree it expects, (b) what it registers, and (c) which classes are framework-agnostic enough to reuse in Laravel.
• Decision point: either (1) write a thin Laravel adapter that registers the bundle's listeners manually, or (2) skip the bundle and use elastic/apm-agent-php directly with your own middleware. For most Laravel apps, option 2 is less surface area.
• First use case: instrument a single route end-to-end — start a named transaction, set the route and HTTP method as labels, end it in finally — and confirm the transaction appears in Kibana APM before instrumenting anything else.

Implementation Patterns

• Adapter service provider: create a ApmServiceProvider that binds the bundle's transaction/span services into Laravel's container and translates Symfony EventDispatcherInterface dispatches into Laravel events (or bypasses the dispatcher and calls the services directly from middleware).
• HTTP middleware: an ApmTransaction middleware that starts a transaction in handle() and ends it in terminate()/finally, labelling route name, method, status code, and authenticated user id. Keep it registered globally but no-op when ELASTIC_APM_ENABLED=false.
• Queue instrumentation: hook JobProcessing/JobProcessed/JobFailed listeners to open a transaction per job with the job class as the transaction name. This is where the bundle's console/job listeners can be reused if they aren't tied to Symfony's console events.
• Config bridging: mirror the bundle's Symfony config tree in config/elastic_apm.php, then push those values into the container as parameters so the reused services receive what they expect. Drive enabled and transaction_sample_rate from env so local, test, and CI never emit spans.
• Labels over high-cardinality tags: set custom labels (user id bucket, tenant, queue name) via the agent API rather than baking values into transaction names — otherwise your Kibana aggregations fragment.
• Testing: use an in-memory/fake transport or a no-op agent so feature tests don't require an APM Server; assert that a transaction was started with the expected name.
• Upgrade workflow: keep a branch pinned to 1.x and diff behaviour against 2.0.0 on the same endpoint before rolling out — a refactor release with a one-line changelog is exactly the case where you verify rather than trust.

Gotchas and Tips

• Framework mismatch is the dominant pitfall. Symfony's Kernel never boots in Laravel, so the bundle's Extension::load() and boot() never run. Missing configuration surfaces as "agent enabled, no data" rather than as an exception.
• v2.0.0 has almost no changelog. "Refactor bundle" plus a single PR means namespace moves, config key renames, and dropped services are all plausible. Pin the exact version in composer.json and read the diff, not the release notes.
• Troubleshoot at the agent layer first. No transactions in Kibana is usually: extension not loaded, wrong server_url/secret_token, TLS failure, or transaction_sample_rate set to 0. Set elastic_apm.log_level=debug and check the agent log before suspecting the bundle.
• Long-running processes: under Octane or persistent queue workers, open and close a transaction per request/job. A transaction started once at boot produces meaningless durations and memory growth.
• PII leakage: request bodies, query strings, and Authorization headers can end up in spans. Configure sanitization and set ELASTIC_APM_CAPTURE_BODY=off / CAPTURE_HEADERS=false where required.
• Overhead: spans are not free. Avoid instrumenting inside loops; keep transaction_sample_rate below 1.0 on high-traffic endpoints.
• Extension points worth wrapping: the bundle's event subscribers are the only genuinely reusable surface for a Laravel adapter. Hide them behind your own Tracer interface so swapping to the raw agent or a Laravel-native package later is a one-file change.
• Evaluate whether you need it at all. If your goal is HTTP and job tracing in Laravel, a ~100-line middleware plus the official agent gives you the same result with far less coupling to a low-traffic Symfony bundle.