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
   

   This boots the Pulse dashboard on http://localhost:8080 (or your configured port).

4. First Use Case:

   • Access the dashboard to immediately see real-time metrics:
     • Requests: HTTP request performance (response times, status codes).
     • Exceptions: Uncaught exceptions with stack traces.
     • Jobs: Queue job processing times and failures.
     • Logs: Tail live application logs.
     • Servers: Server resource usage (CPU, memory, disk).

Implementation Patterns

Core Workflows

1. Monitoring Application Health:

   • Real-Time Dashboard: Use the dashboard to monitor live metrics without leaving your IDE. The dashboard auto-refreshes every 5 seconds by default.
   • Threshold Alerts: Configure thresholds for slow requests, jobs, or queries in config/pulse.php:

     'thresholds' => [
         'requests' => [
             'slow' => 500, // ms
         ],
         'jobs' => [
             'slow' => 10000, // ms
         ],
         'queries' => [
             'slow' => 200, // ms
         ],
     ],
     

2. Custom Metrics with Pulse::record():

   • Track custom business metrics (e.g., checkout conversions, API call latencies):

     use Laravel\Pulse\Facades\Pulse;
     
     // Record a custom metric
     Pulse::record('checkout.conversions', 1);
     
     // Set a custom value (e.g., for dashboards)
     Pulse::set('current_users', $userCount);
     

   • Access these in the "Custom" tab of the dashboard.

3. Queue Monitoring:

   • Monitor job processing times and failures in the "Jobs" tab.
   • Filter by queue name or job class. Click on a job to see its payload and execution duration.

4. Exception Tracking:

   • View uncaught exceptions in the "Exceptions" tab, sorted by frequency.
   • Click an exception to see all occurrences, including stack traces and request context.

5. Log Inspection:

   • Tail live logs in the "Logs" tab. Filter by log level (e.g., error, info) or search for specific messages.

6. Server Metrics:

   • Monitor CPU, memory, and disk usage per server in the "Servers" tab.
   • Useful for identifying resource bottlenecks (e.g., high memory usage during peak traffic).

7. Database Queries:

   • Identify slow queries in the "Queries" tab. Sort by execution time or frequency.
   • Click a query to see its SQL, bindings, and execution time.

8. Livewire Monitoring:

   • Track Livewire component performance (load times, interactions) in the "Livewire" tab.
   • Useful for debugging slow components or memory leaks.

Integration Tips

1. Environment-Specific Configuration:

   • Disable Pulse in production or local environments by setting PULSE_ENABLED=false in .env:

     PULSE_ENABLED=false
     

   • Use PULSE_PORT=8081 to change the dashboard port.

2. Custom Cards:

   • Extend Pulse with custom cards by publishing the assets and creating a service provider:

     php artisan vendor:publish --provider="Laravel\Pulse\PulseServiceProvider" --tag="pulse-config"
     

   • Add your card to config/pulse.php under the cards array:

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

3. Sampling:

   • Reduce overhead by sampling requests or queries. Configure in config/pulse.php:

     'sampling' => [
         'requests' => 10, // Sample 10% of requests
         'queries' => 20,  // Sample 20% of queries
     ],
     

4. Authentication:

   • Secure the dashboard with basic auth or middleware. Add to routes/pulse.php:

     Route::middleware(['auth'])->group(function () {
         // Dashboard routes
     });
     

5. Data Retention:

   • Configure how long data is retained (default: 14 days):

     'trim' => [
         'duration' => 14, // Days
     ],
     

   • Run the pulse:trim command manually to clean up old data:

     php artisan pulse:trim
     

6. Private Tunnel (Local Development):

   • Use pulse:tunnel to expose your local Pulse dashboard securely:

     php artisan pulse:tunnel
     

   • Access the tunnel URL provided in the output.

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Pulse adds minimal overhead (~1-2% for most applications), but avoid running it in high-traffic production environments unless necessary.
   • Fix: Use sampling ('sampling' => ['requests' => 10]) to reduce load.

2. Redis Memory Leaks:

   • Older versions of Pulse could cause memory leaks when using Telescope alongside Pulse.
   • Fix: Update to Pulse v1.3.2+ or disable Telescope if not needed.

3. Livewire Version Conflicts:

   • Pulse requires Livewire v3 or v4. Using an unsupported version may break the Livewire card.
   • Fix: Update Livewire or patch your version (see #464).

4. Database Prefixing Issues:

   • Pulse may not work correctly with prefixed database tables (e.g., pulse_*) in PostgreSQL or SQLite.
   • Fix: Update to Pulse v1.2.3+ or manually adjust the migration.

5. Dark Mode Quirks:

   • Some UI elements may not respect dark mode settings if the theme config is misconfigured.
   • Fix: Set PULSE_THEME=dark in .env or use system for OS-level preference.

6. Private Tunnel Security:

   • The pulse:tunnel command exposes your dashboard publicly. Avoid using it in sensitive environments.
   • Fix: Restrict tunnel usage to local environments only (configurable in config/pulse.php).

7. Enum Support:

   • Older Laravel versions (<10.0) may throw errors when using enums with Pulse::record().
   • Fix: Update to Pulse v1.7.1+ or cast enums to strings:

     Pulse::record('status', $enum->value);
     

Debugging Tips

1. Dashboard Not Loading:

   • Ensure the pulse:start command is running and the port is free.
   • Check for errors in the terminal or browser console. Common issues:
     • Port already in use: Change PULSE_PORT in .env.
     • Missing dependencies: Run npm install && npm run dev in the resources/js directory.

2. Missing Metrics:

   • Verify that Pulse is enabled (PULSE_ENABLED=true).
   • Check if the pulse table exists in your database. Run migrations if needed:

     php artisan migrate
     

3. Slow Queries Not Showing:

   • Ensure your database driver supports query logging (e.g., MySQL, PostgreSQL). SQLite may not log queries.
   • Fix: Add DB::enableQueryLog() at the start of your request lifecycle (e.g., in a middleware).

4. Livewire Card Blank:

   • Ensure Livewire is installed and the livewire package is patched (if using an older version).
   • Fix: Update Livewire or apply the patch from #464.

5. Custom Metrics Not Appearing:

   • Ensure you’re using Pulse::record() or Pulse::set() correctly. Metrics are stored in the pulse_metrics table.
   • Fix: Check the pulse_metrics table directly or verify your code is executing during a monitored request.

Extension Points

1. Custom Cards:
   • Create a custom card by extending Laravel\Pulse\Cards\Card:

     namespace App\Pulse\Cards;
     
     use Laravel\Pulse\Cards\Card;
     
     class CustomCard extends Card
     {
         public function title(): string
         {
             return 'Custom Metric';
         }
     
         public function graph()
         {
             return $this->lineChart()
                 ->title('Custom Data Over Time')
                 ->data($this->getCustomData());
         }
     
         protected function getCustomData()