- How do I install jackwh/laravel-new-relic in a Laravel application?
- Install it with Composer using composer require jackwh/laravel-new-relic. The package registers itself through Laravel package auto-discovery, so no manual service provider entry is needed. You must already have the New Relic PHP agent installed and enabled on the host. Then publish the config file with php artisan vendor:publish and set your New Relic app name and license key through the agent's ini settings.
- Which Laravel versions does this package support?
- Version 1.4.0 supports Laravel 11 and Laravel 12. Laravel 10 support was dropped because it reached end of life in February 2025. Any service still running Laravel 10 must stay pinned to v1.3.x, which means it will not receive later fixes, including the queue transaction lifecycle fix.
- How does transaction naming work for routes and console commands?
- The package ships middleware and listeners that map incoming requests to New Relic transactions named after the matched route, instead of generic controller or URI strings. It also maps console commands, Artisan invocations, and queue jobs to meaningful transaction names so they show up clearly in APM. The result is route-level and job-level visibility in New Relic dashboards and traces.
- How do I monitor queued jobs with New Relic using this package?
- The package instruments Laravel's queue job lifecycle so each job is reported under a named New Relic transaction, and it supports distributed tracing across queued work. As of v1.4.0, transactions end on the JobAttempted event rather than JobProcessed, so failed and retried jobs close their segment properly instead of being left open. This means queue duration, error rate, and throughput data include failures that were previously misreported or invisible.
- Can I exclude certain exceptions from being reported to New Relic?
- Yes. The publishable config file lets you list exception classes that should be ignored so routine or expected errors do not flood your New Relic error inbox. Exception reporting is hooked through Laravel's event system, so ignored entries are filtered before they reach the agent. Review this list after upgrades in case new config keys or renamed options are introduced.
- Does this package replace the New Relic PHP agent?
- No. It is a thin instrumentation bridge that configures and extends the New Relic PHP agent, which must already be installed and running. The package adds no daemon, no separate storage, and no database schema changes. It is essentially a service provider plus a small set of listeners and middleware on top of the agent.
- Why did my queue transaction metrics change after upgrading to v1.4.0?
- v1.4.0 changed the queue transaction lifecycle so transactions end on JobAttempted instead of JobProcessed. Because JobProcessed only fires after a successful job, failed and retried jobs previously could leave transactions open until agent-side timeout or truncation. After upgrading, failing jobs are reported correctly, so queue durations, error rates, and throughput counts will shift. Roll out to a canary environment first and re-baseline dashboards and alerts built on v1.3.x data.
- Can I enable or disable instrumentation per environment?
- Yes. The package is configured through a publishable config file with environment-specific settings, and it follows the New Relic agent's own enablement settings such as newrelic.enabled. This lets you keep instrumentation active in production and staging while turning it off in local development or test environments. Use environment variables so the same codebase behaves correctly per environment.
- Will this package conflict with Laravel Telescope or Horizon?
- No. It works at the New Relic agent layer rather than competing for Laravel's request and job hooks, so it sits alongside Telescope, Horizon, and structured logging without conflict. Each tool serves a different purpose: the package feeds APM data to New Relic, while Telescope and Horizon provide local debugging and queue inspection. You can run them together in the same application.
- How do I report custom metrics or handle errors the package does not cover?
- The package focuses on automatic instrumentation: route and job transaction naming, distributed tracing, and exception reporting through Laravel's event system. For anything beyond that, call the New Relic PHP agent's functions directly, such as newrelic_custom_metric and newrelic_notice_error, from your own code. This keeps custom instrumentation explicit while the package handles the standard Laravel lifecycle events.