Laravel New Relic Laravel Package

Getting Started

Requirements for v1.4.0

• PHP 8.2+ and Laravel 11 or 12 — Laravel 10 support was dropped in this release. If your app is still on Laravel 10, Composer will hold you at v1.3.x; pin ^1.3 explicitly so an unrelated composer update doesn't surprise you.
• The New Relic PHP agent extension (newrelic.so) must be installed and loaded in the SAPI that actually serves traffic. The package is a thin wrapper — without the extension it degrades to a no-op (which is intentional and is what makes local/test environments safe).

Minimal setup

1. composer require jackwh/laravel-new-relic
2. Install the agent, set newrelic.appname and newrelic.license in the agent's newrelic.ini, and confirm the daemon is running.
3. Publish the config (php artisan vendor:publish and pick the package's config/provider) and commit config/newrelic.php.
4. Restart PHP-FPM/Octane and hit a route.

Where to look first

• config/newrelic.php — transaction naming, ignored paths, custom attributes. This is where 90% of day-to-day tuning happens.
• The service provider — it registers the middleware/listeners that do the naming and job instrumentation. Read it before debugging "why is this transaction named this way".

First use case: give transactions meaningful names. Out of the box, New Relic tends to show raw URIs; configuring route-based naming turns /orders/8823 into orders.show, which is what makes APM transaction charts, error rates, and alerts actually usable.

Implementation Patterns

Transaction naming

• Prefer route-name or controller/action naming over raw URI. It collapses dynamic segments and keeps cardinality sane.
• For non-HTTP entry points (console commands, scheduled tasks, queue workers), name explicitly — otherwise everything funnels into cli/queue and you can't alert on a specific job.

Ignoring noise

• Add health checks, /horizon, /telescope, /livewire/*, webhook receivers, and asset/prefetch hits to the ignored list. Ignored transactions still cost agent time but won't pollute your Apdex or error-rate baselines.
• Group ignores by purpose with comments — this list rots fast and nobody remembers why /foo is excluded.

Custom attributes for segmentation

• Attach user ID, tenant/account ID, plan tier, feature flag state, and request ID as custom attributes so you can filter error analytics by customer.
• Do it in a small dedicated middleware rather than sprinkling calls through controllers; keep it after auth so Auth::id() is populated.
• Watch out for PII and attribute-cardinality limits — never attach raw emails, tokens, or unbounded values.

Queue jobs (changed behaviour in v1.4.0)

• Each job runs as a New Relic background transaction.
• v1.4.0 ends the transaction on JobAttempted rather than JobProcessed. This is the important fix: JobProcessed never fires for a job that throws, so previously failed/retried jobs could leave the transaction dangling or mis-timed. Failed jobs now close cleanly and retries get their own correctly-scoped transaction.
• Practical consequence: don't end the transaction yourself in job code or in your own JobProcessed/JobFailed listeners. If you have custom listeners that call the New Relic end-transaction API, remove or guard them or you'll double-end.
• For long jobs, prefer explicit segments (custom events/newrelic_start_transaction-style instrumentation around expensive sub-operations) over relying on total job duration.

Environment strategy

• Enable in staging and production — staging is where you validate naming and ignore rules without polluting prod baselines.
• Disable in local/testing; the no-op behaviour means you can keep the package installed everywhere and only toggle per environment.
• Use distinct newrelic.appname per environment so staging data never mixes with production.

Integration tips

• Pair the package with deploy markers (a small post-deploy artisan command hitting the New Relic API) so you can correlate error spikes with releases.
• Add a smoke check to CI/deploy: assert the extension is loaded in the target SAPI, otherwise a silently-broken agent goes unnoticed for weeks.

Gotchas and Tips

Laravel 10 drop is the real breaking change

• The queue fix is a behaviour change you should be aware of; the version constraint is the one that will actually block upgrades. Check composer.json and any downstream packages that pin this one. There are no code-level API changes to migrate.

Extension loaded ≠ agent working

• php -m in a container shell often checks the CLI SAPI, not FPM. Verify via a route that dumps extension_loaded('newrelic'), or check newrelic.daemon.* logs.
• If the daemon isn't reachable, transactions are silently dropped. Symptom: "the package does nothing" with no PHP error. Check newrelic.daemon.logfile and the socket path, especially across Docker/host boundaries.

Naming cardinality explosions

• Naming by raw URI, or including IDs, blows up the transaction list and destroys aggregation. Also avoid naming by user-supplied query params.
• 404s from bots are the classic culprit — combine proper naming with ignores.

Queue debugging

• Because transactions now end on JobAttempted, a job that hangs will show a long transaction rather than an unclosed one. That's better, but it means "slow job" and "stuck job" look similar — use custom segments to distinguish.
• Long-lived workers (queue:work without --once) keep the agent's per-process state alive; restart workers on deploy so config/appname changes take effect.

Testing

• You cannot assert against real New Relic calls in unit tests without the extension. Structure code so attribute-setting lives in a thin, injectable layer you can spy on, rather than asserting on agent output.
• Prefer asserting what you would have sent (a custom attribute array, a naming decision) over end-to-end agent behaviour.

Extension points

• The package's config and middleware registration are the sanctioned hooks. For anything unusual (custom transaction naming logic, conditional ignoring), extend or replace the naming strategy from config rather than forking the provider — you want clean upgrades across minor releases like this one.
• When filing or debugging an issue, state the package version, Laravel version, PHP SAPI and agent version up front; "works on CLI, fails on FPM" is the single most common report.