Messenger Newrelic Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require arxus/messenger-newrelic
   

2. Add middleware to your default bus in config/packages/messenger.yaml:

   framework:
       messenger:
           buses:
               default:
                   middleware:
                       - Arxus\NewrelicMessengerBundle\Middleware\NewRelicMiddleware
   

3. Verify New Relic integration by checking the New Relic dashboard for new transactions named after your message classes.

First Use Case

• Debugging message processing: If a message fails silently in production, New Relic will now show the transaction (message name) and its duration, making it easier to trace issues.
• Monitoring performance: Track how long specific message handlers take to execute, helping identify bottlenecks.

Implementation Patterns

Core Workflow

1. Middleware Execution:

   • The NewRelicMiddleware wraps message handling in a New Relic transaction.
   • Transaction name defaults to the message class name (e.g., App\Message\SendEmailMessage).
   • Use NameableNewrelicTransactionInterface to customize transaction names (see below).

2. Custom Transaction Names: Implement NameableNewrelicTransactionInterface in your message class:

   use Arxus\NewrelicMessengerBundle\Middleware\NameableNewrelicTransactionInterface;
   
   class SendEmailMessage implements NameableNewrelicTransactionInterface
   {
       public function getNewRelicTransactionName(): string
       {
           return 'custom.email.sender';
       }
   }
   

3. Asynchronous vs. Synchronous:

   • Works seamlessly with both async (e.g., doctrine, amqp) and sync transports.
   • For async transports, ensure New Relic’s background job monitoring is enabled.

4. Conditional Usage: Disable the middleware in config/packages/dev/messenger.yaml for local development:

   framework:
       messenger:
           buses:
               default:
                   middleware:
                       - ~ # Disable NewRelicMiddleware in dev
   

Integration Tips

• New Relic Configuration: Ensure your newrelic.ini includes:

  transaction_tracer.record_sql=obey_transaction_name
  transaction_tracer.record_ajax=true
  

• Symfony Messenger Transports: Test with multiple transports (e.g., doctrine, amqp, sync) to verify consistency.
• Error Handling: New Relic will automatically capture errors in message handlers. Use this to correlate failures with specific messages.

Gotchas and Tips

Pitfalls

1. Transaction Naming Collisions:

   • Defaults to FQCN (e.g., App\Message\SendEmailMessage). Override with NameableNewrelicTransactionInterface if names are ambiguous.
   • Example: Two similar messages (SendEmailMessage and SendNewsletterMessage) may blend into one transaction in dashboards.

2. New Relic Agent Version:

   • Requires New Relic PHP agent v7.0+ for full support. Older versions may ignore the middleware.
   • Verify with:

     if (!class_exists(\NewRelic::class)) {
         throw new \RuntimeException('New Relic PHP agent not installed.');
     }
     

3. Performance Overhead:

   • Minimal, but avoid overusing in high-throughput systems. Benchmark if processing >10K messages/minute.
   • Disable in config/packages/prod/messenger.yaml if monitoring isn’t critical.

4. Symfony 6/7 Specifics:

   • The package supports Symfony 6/7 via symfony/messenger:^6.0 or ^7.0. Ensure your composer.json aligns:

     "require": {
         "symfony/messenger": "^7.0"
     }
     

Debugging

• Missing Transactions:
  • Check if New Relic is enabled (php -r "var_dump(\NewRelic::isEnabled());").
  • Verify the middleware is loaded (enable Symfony’s debug toolbar and inspect the bus middleware list).
• Incorrect Names: Use dd($message::class) in your handler to confirm the FQCN matches expectations.

Extension Points

1. Custom Transaction Attributes: Extend the middleware to add custom attributes (e.g., message ID, payload size):

   use Arxus\NewrelicMessengerBundle\Middleware\NewRelicMiddleware;
   
   class CustomNewRelicMiddleware extends NewRelicMiddleware
   {
       protected function startTransaction(object $message): void
       {
           \NewRelic\Agent::addCustomParameters([
               'message_id' => $message->getId(),
               'payload_size' => strlen(serialize($message)),
           ]);
           parent::startTransaction($message);
       }
   }
   

   Then replace the default middleware in messenger.yaml with your custom class.

2. Conditional Middleware: Skip the middleware for specific messages (e.g., health checks):

   framework:
       messenger:
           buses:
               default:
                   middleware:
                       - Arxus\NewrelicMessengerBundle\Middleware\NewRelicMiddleware
                       - App\Middleware\SkipForHealthCheckMiddleware
   

3. Testing: Mock New Relic in tests to avoid real API calls:

   use Arxus\NewrelicMessengerBundle\Middleware\NewRelicMiddleware;
   
   $middleware = new NewRelicMiddleware();
   $middleware->handle($message, new TestHandler(), function () {
       // Test logic here
   });