jackwh/laravel-new-relic
Adds New Relic APM instrumentation to Laravel apps: names transactions by route, reports exceptions and custom metrics, and provides middleware plus config for queue jobs, ignored exceptions, and environment-specific settings. Simple setup for better Laravel performance monitoring.
jackwh/laravel-new-relic is a thin instrumentation bridge between Laravel and the New Relic PHP agent. It does not replace the agent; it configures and extends it. The package's value is in three areas: (1) transaction naming (mapping routes, console commands, queue jobs, and artisan invocations to meaningful New Relic transaction names), (2) distributed tracing across queued jobs, and (3) exception/error reporting hooks via Laravel's event system. Architecture fit is high for any Laravel app already running the New Relic PHP agent — it is a service provider plus a small set of listeners, with no daemon, no separate storage, and no schema changes. Integration is essentially "install the agent, add the package, publish config."
The v1.4.0 release carries two changes of consequence and one housekeeping change:
JobProcessed, which fires only after a job completes without throwing. The change ends them on JobAttempted, which fires after every attempt regardless of outcome. In practice this means failed and retried jobs now close their New Relic transaction segment properly rather than leaving it open until agent-side timeout/truncation. This is a correctness fix with a metrics discontinuity: after upgrading, expect queue transaction durations, error rates, and throughput counts to shift — failed jobs that were previously under- or mis-reported will now be visible. Dashboard and alert baselines built on v1.3.x queue data will move and need re-baselining. This is the single item that warrants a deliberate rollout rather than a passive dependency bump.actions/checkout and fetch-metadata. CI-only, no runtime impact. Routinely ignorable but worth noting they are GitHub Actions major-version jumps, so CI behavior on the project's own pipeline may change.Technical risk is low-to-moderate: the code surface is small and the failure mode of the package itself is "telemetry degrades," not "application breaks." The real risk is observability risk in both directions — silent loss of queue visibility on upgrade, or a flood of newly-visible failed-job errors that trip alerts. Key questions: does the agent version in our fleet support the transaction semantics this relies on; do we have any Laravel 10 services still consuming this package; and can we diff queue transaction counts before/after in a canary?
Stack fit is straightforward: standard Laravel service provider registration via package auto-discovery, a publishable config file, and environment-driven enablement. There is no infrastructure to stand up beyond the New Relic PHP agent, which is presumably already a platform prerequisite. The package sits cleanly alongside existing Laravel observability (Telescope, Horizon, structured logging) without conflict, since it works at the agent layer rather than competing for the same hooks.
Migration path for v1.3.0 → v1.4.0 is a routine composer update for anyone on Laravel 11+, with two caveats. First, if the config file was published and customized, re-check it against the package's config for any new or renamed keys — the queue listener change may not require config edits but should be verified. Second, treat the queue change as behaviorally significant: sequence the upgrade so that a low-traffic or canary environment is instrumented first, and compare queue transaction volume, error rate, and p95 duration against the prior week before fleet-wide rollout.
Compatibility: Laravel 11 and 12 are in scope; Laravel 10 is out. Any L10 service must either stay pinned to v1.3.x (and accept missing the queue fix) or be upgraded to L11+ before taking v1.4.0. This is the only hard blocker and it should be resolved as a dependency inventory question, not a per-service surprise.
Sequencing recommendation: (1) inventory Laravel major versions across services consuming the package; (2) upgrade remaining L10 services to L11+ or formally accept the pin; (3) roll v1.4.0 to a canary service handling queued jobs; (4) re-baseline queue dashboards and alerts against post-upgrade data; (5) fleet rollout; (6) retire v1.3.x pins.
Maintenance burden is low. The package is small, maintained by an individual maintainer with active Dependabot and external contributions (this release includes a first-time contributor), and the release cadence appears steady without churn. The main ongoing cost is tracking Laravel major-version support windows — the v1.4.0 Laravel 10 drop is the pattern to expect, so the team should anticipate a similar boundary when Laravel 11 reaches EOL and budget a routine upgrade rather than treating each as a surprise.
Support and failure modes are favorable: if the package misbehaves or the agent is absent, the application continues to serve traffic and telemetry is simply degraded. The realistic failure modes are (a) agent not installed or misconfigured on a host, causing silent gaps; (b) transaction naming rules missing routes or commands, producing Controller@action-style or generic names that fragment New Relic data; (c) after this release, queue data appearing to regress because it is now correct and differs from historical baselines; and (d) an L10 service pinned to v1.3.x drifting from the rest of the fleet. Only (c) has cross-team blast radius, via alerting.
Scaling considerations are essentially the New Relic agent's, not the package's — APM sampling and agent overhead are the governing factors, and this package adds negligible per-request cost. Ramp-up for engineers is minimal (config file plus docs), but the team should treat knowledge of transaction naming conventions as the real onboarding artifact: it is what makes the New Relic data usable, and it is the thing most likely to be set once and forgotten. Worth documenting the naming scheme alongside the service.
Recommended action: adopt v1.4.0, but gate it behind a canary on a queue-heavy service and re-baseline queue dashboards before fleet rollout. Resolve the Laravel 10 question first, since it is the only genuine blocker.
How can I help you explore Laravel packages today?