gecole / pulse

dev-master 2026-11-08 15:11 UTC

Requires

• php: >=8.3
• ext-pdo: *
• ext-pdo_sqlite: *
• gecole/framework: dev-main

proprietary

• framework
• sqlite
• monitoring
• Metrics
• pulse
• gecole

Published on Packagist.org on 2026-11-08 15:11 UTC

README

Real-time request, query, exception and queue metrics with a small dashboard. It ships as an optional package so the framework core stays dependency-free.

composer require gecole/pulse

Add the provider:

// config/app.php
'providers' => [
    // …
    \Gecole\Pulse\PulseServiceProvider::class,
],

Open http://localhost:8000/pulse. The provider is enabled outside production by default; set PULSE_ENABLED=false to turn it off everywhere.

Publish the editable configuration when you need to change it:

php bin/console vendor:publish --tag=config
# config/pulse.php now exists; use --force to replace an existing copy

Its own database

Pulse writes per-minute aggregates to storage/framework/pulse.sqlite through a direct PDO handle. It never uses the application connection, so measuring a query cannot generate another measured query. Point it elsewhere with PULSE_DATABASE or the published config/pulse.php.

// config/pulse.php
return [
    'enabled' => (bool) env('PULSE_ENABLED', true),
    'path' => 'pulse',
    'database' => storage_path('framework/pulse.sqlite'),
    'public' => false,      // loopback requests are allowed by default
    'retention' => 168,     // hours of buckets kept
    'ignore' => ['pulse', 'health', 'favicon.ico'],
    'max_queries' => 100,
];

Only loopback requests reach the dashboard unless public is true. When the dashboard is exposed through a proxy or another auth layer, enable public and keep that layer in front of it.

What is measured

Metric	Details
requests	count, total/average/max duration, busiest and slowest endpoints
queries	count, total/average/max duration, slowest normalized SQL
responses	status distribution and 5xx error rate
exceptions	unhandled exception classes
queue	processed, released and failed jobs
schedule	scheduled task runs

Events are folded into (minute, type, key) rows as they happen, so dashboard queries stay small and old buckets are pruned by retention.

Commands

php bin/console pulse:clear
php bin/console pulse:prune --hours=168

Notes

• The dashboard is read-only apart from Clear.
• Route caching includes the package routes; clear the route cache after installing or removing the package.
• Metric failures are logged once and never replace an application response.