Pulse Laravel Package

Getting Started

Laravel Pulse is a first-party, database-backed performance dashboard, not a full APM platform. The fastest useful setup is:

1. Install the package:

   composer require laravel/pulse
   

2. Publish the config and migrations:

   php artisan vendor:publish --provider="Laravel\Pulse\PulseServiceProvider"
   php artisan migrate
   

3. Immediately restrict dashboard access in AppServiceProvider::boot():

   use Laravel\Pulse\Facades\Pulse;
   
   Pulse::auth(fn ($request) =>
       app()->environment('local') ||
       $request->user()?->isAdmin()
   );
   

4. Start the long-running workers your setup needs. For server CPU/memory metrics, run php artisan pulse:check under Supervisor on each server. If you use Redis ingest, run php artisan pulse:work under Supervisor too. A one-off cron invocation will not give you the continuous server metrics Pulse expects.

5. Visit /pulse and start with the Slow Requests, Slow Queries, Exceptions, and Queues cards.

The first place to look after installation is config/pulse.php. That file controls recorders, thresholds, sampling, ignore patterns, ingest/storage drivers, trimming, dashboard path/middleware, and cards. The first real use case should be post-deploy triage: identify slow endpoints, slow or repeated queries, failing jobs, and exception spikes before reaching for custom cards.

Implementation Patterns

Use Pulse as an operational triage dashboard. The strongest day-to-day pattern is a short loop: deploy, watch exceptions and slow requests, drill into slow queries, then fix the endpoint or job. Pulse is good at pointing you toward a problem; it is not designed for distributed tracing or deep profiling.

Configure recorders deliberately. Enable only cards/recorders the team will act on. Tune thresholds before lowering sample rates; a threshold that is too low creates noise, while aggressive sampling makes cards statistically misleading. Use ignore patterns for health checks, /pulse, Horizon/Telescope routes, and other high-volume non-business traffic. Slow request, query, and job thresholds can be customized per environment, including regex-based matching for noisy paths.

A typical recorder config pattern looks like:

'recorders' => [
    Laravel\Pulse\Recorders\SlowRequests::class => [
        'enabled' => true,
        'threshold' => 500,
        'sample_rate' => 1,
        'ignore' => ['#^/health$#', '#^/pulse#'],
    ],
    Laravel\Pulse\Recorders\SlowQueries::class => [
        'enabled' => true,
        'threshold' => 100,
        'sample_rate' => 1,
    ],
],

Monitor queues and jobs alongside requests. Pulse is especially useful when a queue-backed app slows down: slow jobs, queue sizes, and exceptions in one dashboard make it easier to distinguish app code problems from worker capacity problems. Keep Horizon or your queue supervisor for operational control; use Pulse for the performance view.

Add custom metrics sparingly. For business-specific visibility, use Pulse::record() and Pulse::set() from Laravel\Pulse\Facades\Pulse, or write a custom recorder. Keep cardinality low: use stable route patterns, job classes, or IDs rather than raw URLs, emails, or unbounded values. Never record inside tight loops without sampling. Custom cards are best for a small number of durable questions, such as failed imports, active tenants, or external API latency.

Use Redis ingest for busier applications. Pulse’s default database ingest is fine for low-traffic apps, but high write volume can add load to the primary database. Redis ingest plus pulse:work decouples capture from storage. Consider a dedicated database connection for Pulse storage so dashboard queries and ingest writes do not compete with application traffic. If you hit ingest upsert failures on certain database setups, check the use_upsert_alias option added in recent releases.

Run server checks per server. In a multi-server setup, run pulse:check on every server and ensure hostnames are stable. Ephemeral containers can produce noisy or misleading server cards; either disable the Servers recorder or give instances predictable names. Recent versions also support sorting options on the Server card.

Treat environments differently. Keep Pulse enabled and useful in staging, but disable it in test/CI (PULSE_ENABLED=false) to avoid unnecessary database writes. In production, combine a restrictive auth callback with a custom path or domain/middleware if the dashboard should not live at the default /pulse.

Gotchas and Tips

• Authorization is the first production gotcha. Pulse is local-only by default; if you expose it in production without Pulse::auth, you risk leaking request paths, exception traces, job names, and query details.
• The dashboard can look empty because workers are not running. Missing Servers data usually means pulse:check is not running under Supervisor. Missing or stale data with Redis ingest usually means pulse:work is not running.
• Long-running workers need supervision and restarts. Both pulse:check and pulse:work are long-running processes. Use Supervisor with autorestart, and avoid running Telescope in the same process where possible; historical memory-leak issues have been fixed, but lightweight workers are still safer.
• Watch storage growth. Pulse data is trimmed according to the configured retention period. Set a retention window your database can tolerate, monitor the Pulse tables, and do not assume the dashboard is free of database cost.
• Sampling changes the meaning of the numbers. A sampled card is useful for trends, not exact counts. Keep sample rates high enough for low-volume critical events such as exceptions and failed jobs.
• High-cardinality keys are a common custom-card mistake. Raw URLs with IDs, user emails, or request payload fragments will bloat storage and make cards unreadable. Normalize to route names, job classes, or bounded identifiers.
• Sanitize what you record. Exception cards and slow outgoing request cards can expose sensitive data. Recent releases strip userinfo credentials from slow outgoing request URLs, but query strings, headers, and exception context still need review. Restrict dashboard access and avoid recording secrets.
• Ignore patterns are regexes. Escape path separators and special characters carefully; a bad pattern can silently fail to filter noisy traffic or filter too much.
• Pulse is not an alerting system. It has no built-in paging or anomaly alerting. Pair it with Sentry/Bugsnag for exception alerts, Horizon for queue operations, and your log/metric platform for long-term retention.
• Extension points are useful but should stay small. Custom recorders, custom cards, ingest drivers, and storage drivers are the intended extension paths. Keep custom cards’ queries bounded by time ranges and indexed columns; a dashboard card that scans a large table will become its own performance problem.
• Livewire compatibility matters. The dashboard is Livewire-based. Unsupported or conflicting Livewire versions, strict CSP rules, or proxy/URL-generation problems can break rendering even when Pulse is recording correctly.