Pulse Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/pulse
   php artisan pulse:install
   

   This publishes the Pulse migration, config, and assets.

2. Run Migrations:

   php artisan migrate
   

3. Start Pulse:

   php artisan pulse:start
   

   Access the dashboard at /pulse (or your configured route).

First Use Case: Monitoring Requests

• Default Monitoring: Pulse automatically tracks HTTP requests, queue jobs, and exceptions.
• Custom Metrics: Use Pulse::record() to log custom events:

  use Laravel\Pulse\Facades\Pulse;
  
  Pulse::record('custom_event', ['key' => 'value']);
  

Key Configuration

• Update .env:

  PULSE_ENABLED=true
  PULSE_TRIM_DURATION=14  # Days to retain data
  

• Configure in config/pulse.php:

  'thresholds' => [
      'requests' => 1000, // ms
      'queries' => 500,   // ms
  ],
  

Implementation Patterns

Daily Workflows

1. Debugging Slow Requests:

   • Navigate to the Requests tab in Pulse.
   • Click on a slow request to see:
     • Execution time breakdown (routes, middleware, jobs).
     • Database queries with execution times.
     • Logs and exceptions.
   • Use the filter by duration feature to isolate slow endpoints.

2. Queue Monitoring:

   • Check the Jobs tab for stuck or failing jobs.
   • Use Pulse::record('job:failed', ['job' => $job]) to log custom job failures:

     try {
         $job->handle();
     } catch (\Exception $e) {
         Pulse::record('job:failed', [
             'job' => $job->getName(),
             'exception' => $e->getMessage(),
         ]);
     }
     

3. Custom Cards:

   • Extend Pulse with custom cards (e.g., for third-party services like Stripe or Mailgun).
   • Example: Create a StripeCard in app/Pulse/Cards/StripeCard.php:

     namespace App\Pulse\Cards;
     
     use Laravel\Pulse\Cards\Card;
     
     class StripeCard extends Card
     {
         public function title(): string
         {
             return 'Stripe Events';
         }
     
         public function graph()
         {
             return $this->lineChart()
                 ->title('Stripe Events Over Time')
                 ->data(fn () => StripeEvent::query()->countByDay());
         }
     }
     

   • Register the card in config/pulse.php:

     'cards' => [
         \App\Pulse\Cards\StripeCard::class,
     ],
     

4. Environment-Specific Tuning:

   • Disable Pulse in local environments for performance:

     'environments' => [
         'local' => false,
     ],
     

   • Use PULSE_TUNNEL_RESTRICT_LOCAL=true to block private tunnel access in local.

5. Real-Time Alerts:

   • Set up thresholds in config/pulse.php:

     'thresholds' => [
         'requests' => [
             'pattern' => 'api/*',
             'duration' => 500, // ms
         ],
     ],
     

   • Pulse will highlight requests exceeding these thresholds in red.

Integration Tips

1. Livewire Integration:

   • Pulse supports Livewire v3/v4 out of the box.
   • Monitor Livewire component performance in the Livewire tab.
   • Customize sorting for Livewire cards:

     'livewire' => [
         'sort_by' => 'duration', // or 'memory', 'count'
     ],
     

2. Database Query Optimization:

   • Use the Queries tab to identify slow queries.
   • Filter by execution time or query pattern (e.g., SELECT * FROM users).
   • Pulse highlights slow queries in the Exceptions tab if they exceed the threshold.

3. Custom Metrics with Pulse::set():

   • Track application-specific metrics (e.g., cache hits/misses):

     Pulse::set('cache_hits', Cache::stats()['hits']);
     Pulse::set('cache_misses', Cache::stats()['misses']);
     

   • Display these in a custom card or use the Metrics tab.

4. Queue Worker Monitoring:

   • Run Pulse alongside your queue workers:

     php artisan queue:work --daemon --tries=3 &
     php artisan pulse:work
     

   • Monitor job processing time and failures in the Jobs tab.

5. Dark Mode and Theming:

   • Configure dark mode in config/pulse.php:

     'theme' => 'dark', // or 'light', 'system'
     

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Pulse adds minimal overhead (~1-2ms per request). For high-traffic apps, consider:
     • Disabling in local or staging:

       'environments' => [
           'local' => false,
           'staging' => false,
       ],
       

     • Adjusting PULSE_TRIM_DURATION to reduce storage usage.

2. Redis Serialization Issues:

   • If using Redis, ensure serialization is compatible (Pulse uses Laravel’s default serializer).
   • For Laravel 13+, update your Redis config to match Pulse’s expectations:

     'options' => [
         'serialize' => Redis::SERIALIZER_PHP,
     ],
     

3. Livewire Version Conflicts:

   • Pulse requires Livewire v3/v4. If using an older version, upgrade or patch Livewire:

     composer require livewire/livewire:^4.0
     

   • For unpatched versions, Pulse will throw an error during startup.

4. Private Tunnel Security:

   • Restrict private tunnel access in local to prevent unauthorized access:

     PULSE_TUNNEL_RESTRICT_LOCAL=true
     

5. Custom Card Loading:

   • Ensure custom cards are autoloaded or manually loaded in AppServiceProvider:

     public function boot()
     {
         Pulse::extend(\App\Pulse\Cards\StripeCard::class);
     }
     

6. Database Prefixing:

   • If using database prefixes (e.g., pulse_), ensure Pulse’s migrations are prefixed correctly:

     'database' => [
         'prefix' => 'pulse_',
     ],
     

7. Enum Support:

   • Pulse supports enums in Pulse::record() and Pulse::set() (Laravel 10+):

     Pulse::record('status', UserStatus::Active);
     

Debugging Tips

1. Clear Pulse Data:

   • Reset Pulse data manually:

     php artisan pulse:clear
     

   • Or truncate tables:

     php artisan migrate:fresh --path=/vendor/laravel/pulse/database/migrations
     

2. Check Logs:

   • Pulse logs errors to storage/logs/pulse.log. Tail logs during development:

     tail -f storage/logs/pulse.log
     

3. Disable Pulse Temporarily:

   • Set PULSE_ENABLED=false in .env to disable without uninstalling.

4. Reload Pulse:

   • After config changes, reload Pulse:

     php artisan pulse:reload
     

5. Memory Leaks:

   • If Pulse consumes excessive memory, check for unclosed connections (e.g., Redis). Update to the latest version to fix leaks:

     composer update laravel/pulse
     

Extension Points

1. Custom Skills:

   • Add skills (e.g., "pulse-development Boost") to highlight specific conditions:

     'skills' => [
         'pulse-development' => [
             'Boost' => function () {
                 return request()->ip() === '127.0.0.1';
             },
         ],
     ],
     

2. Third-Party Integrations:

   • Extend Pulse with APIs like Datadog or New Relic by creating a custom card that fetches remote data.

3. Middleware for Custom Metrics:

   • Log metrics in middleware:

     public function handle(Request $request, Closure $next)
     {
         Pulse::record('middleware:auth', ['user_id' => auth()->id()]);
         return $next($request);
     }
     

4. Custom Graphs:

   • Use Laravel’s charting libraries to extend Pulse’s graphs. Example:

     public function graph()
     {
         return $this->lineChart()
             ->title('API Calls')
             ->data(fn () => Http