Elastic Apm Bundle Laravel Package

Getting Started

Reality check first: this is a Symfony bundle, not a Laravel package. There is no service provider, no config/app.php registration, and none of the Laravel-specific ergonomics (no auto-discovery, no facade). If you're a Laravel dev, your day-to-day use is essentially limited to (a) working inside a Symfony codebase or migrating one, or (b) borrowing its patterns while you wire the underlying elastic/apm-agent-php agent into Laravel yourself.

Minimal steps in a Symfony context:

1. composer require firmaprofesional/elastic-apm-bundle (and confirm the transitive elastic/apm-agent-php agent version it pulls — see Gotchas).
2. Register the bundle in config/bundles.php.
3. Add a config file under config/packages/ with the server URL, service name, and secret token — most of these should be env-driven (ELASTIC_APM_SERVER_URL, ELASTIC_APM_SERVICE_NAME, ELASTIC_APM_SECRET_TOKEN) rather than hard-coded.
4. Ship a request and confirm a transaction shows up in Kibana APM.

Where to look first: the bundle's DependencyInjection/Configuration.php — that's the authoritative list of config keys and their defaults. Then scan EventSubscriber/ (or equivalent) to see exactly what it auto-instruments (HTTP kernel, Doctrine, console). Everything else is just the underlying agent API.

First use case: let the bundle create the HTTP transaction for a controller action, open Kibana APM, and confirm the transaction name and duration. If that works, APM is wired; everything after is span-level detail.

Implementation Patterns

• Rely on auto-instrumentation for the baseline. The bundle's subscribers handle request/response transactions and (typically) Doctrine query spans. Don't hand-roll a transaction around what's already instrumented — you'll get duplicate/nested transactions.
• Inject the tracer for custom spans. For business logic worth measuring (an external HTTP call, a chunk of heavy computation, a third-party SDK), pull the agent's tracer from the container and wrap it: start span → do work → end span. Keep span names low-cardinality (payment.charge, not payment.charge.user_1234).
• Add context, not noise. Set labels (order_id, tenant) on the current transaction/span so Kibana searches are useful. Avoid dumping full payloads — they bloat the index and leak PII.
• Console commands need explicit wrapping. Long-running workers and artisan-style commands won't be traced automatically. Wrap the command body in a transaction and end it, or you'll see only the HTTP side of your app.
• Queue/async work needs manual propagation. The agent's context is per-process. When a job runs on a worker, it starts a fresh, disconnected transaction. To link it back to the web request, pass a trace ID (or the transaction's trace_id) through the job payload and start a child transaction with it. This is the single most common gap.
• Config per environment. Enable in staging/prod, disable in dev/test (the agent is heavy in dev and pollutes the index). Drive enabled, transaction_sample_rate, and log_level from env.
• Version the agent pin. Since this bundle is frozen, pin the underlying elastic/apm-agent-php version explicitly so a transitive bump doesn't silently break instrumentation.

Gotchas and Tips

• It's abandoned. Last release mid-2020, no dependents, zero stars. Treat it as reference code, not a dependency you adopt for a new build. Elastic's official path is the native extension (elastic/apm-agent-php), which instruments any PHP app — including Laravel — without a framework bundle at all.
• The underlying agent is the real constraint. The bundle wraps the old (pure-PHP) agent, which has narrow PHP-version support. On PHP 8+, expect it not to load or to misbehave. The native C extension is the modern replacement and has different env-var names — verify before copying config.
• Laravel has no equivalent of this bundle. In Laravel, use the native extension with php.ini config (elastic_apm.*), and write a small middleware to name transactions after the route ($request->route()->getName()) — otherwise every transaction is named after the path and cardinality explodes.
• Transaction naming is the #1 quality problem. Default naming in non-Symfony apps produces path-based names (/users/1234), which shatters your transaction list. Normalize early.
• Silent failures are the norm. If no data appears, the agent didn't load — check the agent's own log (log_level=debug), confirm extension_loaded('elastic_apm') if you're on the extension, and verify the secret token/server URL with a curl. The bundle won't surface these errors for you.
• Sampling defaults to 1.0. On high-traffic endpoints that's a lot of overhead; drop transaction_sample_rate in prod before you roll out broadly.
• Debugging locally: disable sampling concerns by running against a local APM Server (docker), and use log_level: debug in the agent, not the bundle. The bundle's own logging is thin.
• Extension point: if you do reuse this bundle, the useful seam is its event subscribers — they show you exactly how to attach to Symfony's kernel/Doctrine events. That pattern ports cleanly to Laravel service providers and middleware if you're bridging the two worlds.