Messenger Monitor Bundle Laravel Package

Getting Started

First Steps

1. Installation Add the bundle via Composer:

   composer require zenstruck/messenger-monitor-bundle
   

   Register the bundle in config/bundles.php (Symfony) or ensure it’s auto-discovered (Laravel).

2. Publish Assets Run:

   php artisan vendor:publish --provider="Zenstruck\MessengerMonitorBundle\MessengerMonitorBundle" --tag="assets"
   

   This generates the UI assets in public/build/messenger-monitor.

3. Enable the Bundle Add the route to your routes/web.php (Laravel) or config/routes.yaml (Symfony):

   use Zenstruck\MessengerMonitorBundle\MessengerMonitorBundle;
   
   // Laravel
   MessengerMonitorBundle::routes($router);
   
   // Symfony
   messenger_monitor:
       resource: "@MessengerMonitorBundle/Resources/config/routing.yaml"
   

4. First Use Case Visit /_messenger-monitor (or your configured path) to see:

   • Worker status (running/stopped)
   • Transport queues (messages pending/delayed)
   • Message history (failed/sent)
   • Schedule status (next runs, failures)

Implementation Patterns

Daily Workflows

1. Monitoring Workers

   • Check the "Workers" tab to verify all expected workers are running.
   • Use the "Restart" button to bounce workers without redeploying.
   • Filter by environment (e.g., prod, staging) via query params:

     /_messenger-monitor?env=prod
     

2. Debugging Stuck Messages

   • Navigate to the "Messages" tab → filter by status:failed.
   • Click a failed message to see:
     • Retry options (manual retry or adjust retry delay).
     • Exception stack trace (if available).
   • Use the "Requeue" button to reprocess stuck messages.

3. Transport Management

   • Monitor queue backlogs in the "Transports" tab.
   • Adjust transport settings (e.g., max_retries) via config:

     # config/messenger.yaml
     transports:
         async:
             dsn: "sync://"
             options:
                 max_retries: 5
     

   • Clear stale messages with the "Purge" button (use cautiously).

4. Scheduling Inspection

   • Verify cron jobs in the "Schedules" tab.
   • Check "Last Run" timestamps and "Next Run" for misconfigurations.
   • Adjust schedules via Laravel’s schedule:run or Symfony’s messenger:consume commands.

5. Performance Tuning

   • Use the "Stats" tab to track:
     • Messages processed/second.
     • Worker uptime.
   • Scale workers horizontally by adding more MESSENGER_WORKERS env vars:

     MESSENGER_WORKERS=4 php artisan messenger:consume async --env=prod
     

Integration Tips

• Laravel Notifications Monitor sent notifications in the "Messages" tab (filter by message_type:App\Notifications\*).
• Symfony Messenger Works seamlessly with Symfony’s MessageBus—no extra config needed.
• Custom Middleware Extend the bundle’s twig templates (located in vendor/zenstruck/messenger-monitor-bundle/Resources/views) to add custom fields (e.g., user IDs for logged-in workers).
• API Access Use the underlying MessengerMonitorBundle\Monitor\Monitor service to build custom CLI tools:

  $monitor = $this->container->get('messenger_monitor.monitor');
  $workers = $monitor->getWorkers();
  

Gotchas and Tips

Pitfalls

1. Permission Issues

   • The /_messenger-monitor route requires ROLE_MESSENGER_MONITOR by default.
   • Fix: Add to your security config (Symfony) or middleware (Laravel):

     // Laravel (app/Http/Kernel.php)
     'web' => [
         \Zenstruck\MessengerMonitorBundle\Http\Middleware\Authenticate::class,
         // ...
     ];
     

   • Symfony:

     # config/packages/security.yaml
     access_control:
         - { path: ^/_messenger-monitor, roles: ROLE_MESSENGER_MONITOR }
     

2. Worker Visibility Lag

   • Workers may take 5–10 seconds to appear after starting.
   • Workaround: Refresh the page or use the "Refresh" button.

3. Message Retention

   • Failed messages are stored in the database. Large backlogs may bloat your DB.
   • Tip: Purge old messages via:

     php artisan messenger:failed-table:purge --hours=72
     

4. Transport-Specific Quirks

   • Doctrine Transport: Requires doctrine/messenger bundle.
   • Redis Transport: Ensure Redis is running and accessible.
   • Sync Transport: Messages won’t appear in the UI (they’re processed immediately).

5. Custom Message Classes

   • If messages don’t appear, ensure they’re serializable (implement Serializable or use #[AsMessage] attribute).
   • Debug: Check config/messenger.php for serializer settings.

Debugging Tips

• Log Level: Increase MESSENGER_LOG_LEVEL to debug for verbose worker logs.
• Twig Debug: Enable Twig debug mode to inspect UI templates:

  // config/packages/twig.yaml
  debug: '%kernel.debug%'
  

• Database Dumps: Export failed messages for analysis:

  php artisan messenger:failed-table:dump --path=/tmp/failed_messages.json
  

Extension Points

1. Custom Tabs Add new tabs by extending the MessengerMonitorBundle\Monitor\Monitor service and overriding the getTabs() method.

2. Message Metadata Attach custom metadata to messages via middleware:

   use Symfony\Component\Messenger\Attribute\AsMessageHandler;
   
   #[AsMessageHandler]
   public function handle(MyMessage $message, MessageBusInterface $bus) {
       $message->setMetadata(['custom_key' => 'value']);
   }
   

3. Theming Override the default Twig templates by publishing them:

   php artisan vendor:publish --provider="Zenstruck\MessengerMonitorBundle\MessengerMonitorBundle" --tag="templates"
   

   Then modify resources/views/messenger-monitor/.

4. API Endpoints Create custom API routes using the Monitor service:

   use Zenstruck\MessengerMonitorBundle\Monitor\Monitor;
   
   public function workerStats(Monitor $monitor) {
       return response()->json($monitor->getWorkers());
   }