README

See into any queue.

Periscope is a universal queue monitor, and manage for Laravel — a driver-agnostic alternative to Laravel Horizon. It works with any queue driver: Redis, database, SQS, Beanstalkd, and more, because it collects telemetry through Laravel's built-in queue events rather than reading driver-specific internals.

Features
Requirements
Installation
Running workers
Scheduling
Authorization
Metrics endpoint
Alerts
Tags
Batches
Scheduled commands
Performance percentiles
Commands
Screenshots
Testing
Contributing
License

Features

Universal — works with redis, database, sqs, beanstalkd, and sync queue drivers
Real-time dashboard built on Livewire 4 + Tailwind 4 — no CDN, ships with a compiled CSS bundle
Per-attempt tracking — every retry recorded with its runtime and exception, shown as a timeline on the job detail page
Grouped exceptions — aggregate by class + message so you see "this RuntimeException hit 47 times" instead of 47 rows, with drill-down to individual occurrences
Batch tracking — live progress for Bus::batch() jobs with cancel action
Scheduled command monitoring — every Schedule::command() run recorded with runtime and failure reason
Performance percentiles — p50 / p95 / p99 of runtime and wait, per queue
Memory tracking — peak memory captured per attempt
Alert history — every fired rule persisted, searchable, and dismissible
Live queue depth via driver adapters — pending, delayed, and reserved counts on the Queues page
Throughput chart — last 60 minutes of processed vs failed jobs, polled every 10s
Worker pools — config-driven supervisors with optional auto-balance that moves processes between queues based on backlog depth
Lifecycle control — start / pause / continue / terminate for deploy-friendly operation
Failed job management — search, filter, retry, forget, and bulk actions
Alerts — failure spike, long wait, stale worker; delivered via mail, Slack, or webhook
Prometheus + JSON metrics endpoint for external monitoring stacks (Grafana, Datadog, etc.)
Authorization gate — viewPeriscope ability, scoped to local by default
Rolling metrics — per-minute buckets rolled up into hourly, with configurable retention per tier
Tag filtering via Laravel's Queueable::tags()

Requirements

PHP 8.2+
Laravel 11, 12, or 13
Livewire 4

Installation

composer require maherelgamil/periscope
php artisan periscope:install
php artisan migrate

Visit /periscope in your browser. The dashboard is gated to local environment by default — see Authorization to expose it elsewhere.

Running workers

Workers must be launched through Periscope so heartbeats show up on the Workers page.

A single worker

php artisan periscope:supervise redis --queue=default,emails

Same flags as queue:work (--tries, --timeout, --memory, --max-jobs, --max-time, etc.).

Config-driven pools (recommended)

Define supervisors in config/periscope.php:

'supervisors' => [
    'default' => [
        'connection' => 'redis',
        'queue' => ['default', 'emails'],
        'processes' => 4,
        'tries' => 1,
        'timeout' => 60,
        'sleep' => 1,
    ],
    'notifications' => [
        'connection' => 'redis',
        'queue' => ['notifications'],
        'processes' => 2,
        'nice' => 10, // deprioritize with Unix nice (ignored on Windows)
    ],
],

Start every pool with:

php artisan periscope:start

The master process respawns any child that crashes and shuts children down cleanly on SIGTERM / SIGINT. Run with --supervisor=default to start only a specific pool.

Auto-balance mode

Set balance: 'auto' and Periscope allocates processes per queue proportional to live queue depth on each cycle, clamped between min_processes and max_processes:

'default' => [
    'connection' => 'redis',
    'queue' => ['high', 'default', 'low'],
    'balance' => 'auto',
    'min_processes' => 1,
    'max_processes' => 10,
],

When all queues are empty, each queue runs min_processes workers. When backlog grows, processes are moved toward the busiest queues automatically.

Deploy-friendly lifecycle

# Stop spawning new workers; let running ones drain
php artisan periscope:pause

# Resume
php artisan periscope:continue

# Shut the master down entirely (use this in your deploy script)
php artisan periscope:terminate

Scheduling

Add the housekeeping commands to routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('periscope:workers:sweep')->everyMinute();
Schedule::command('periscope:snapshot')->hourly();
Schedule::command('periscope:alerts:check')->everyFiveMinutes();
Schedule::command('periscope:prune')->daily();

Authorization

Running periscope:install scaffolds app/Providers/PeriscopeServiceProvider.php in your application (and registers it in bootstrap/providers.php). Edit the gate() method to decide who can access the dashboard in non-local environments:

protected function gate(): void
{
    Gate::define('viewPeriscope', function ($user) {
        return in_array($user?->email, [
            'you@example.com',
        ]);
    });
}

If you don't override it, access is restricted to the local environment. The metrics and health endpoints bypass this gate — see below.

Metrics endpoint (Prometheus / JSON)

Periscope exposes aggregated telemetry at:

/periscope/metrics — Prometheus text format (scrape target)
/periscope/metrics.json — JSON for custom integrations

Both bypass the dashboard authorization by default. Protect them for production with your own middleware (IP allowlist, token guard):

// config/periscope.php
'metrics' => [
    'enabled' => env('PERISCOPE_METRICS_ENABLED', true),
    'middleware' => ['web', \App\Http\Middleware\AllowPrometheus::class],
],

Or disable entirely:

PERISCOPE_METRICS_ENABLED=false

Example Prometheus scrape config:

scrape_configs:
  - job_name: periscope
    metrics_path: /periscope/metrics
    static_configs:
      - targets: ['your-app.test']

Exposed metrics (each labelled with connection and queue where applicable):

Metric	Type	Description
`periscope_jobs_processed_total`	counter	Successfully processed jobs
`periscope_jobs_failed_total`	counter	Jobs that failed
`periscope_jobs_queued_total`	counter	Jobs pushed onto a queue
`periscope_runtime_ms_sum`	counter	Cumulative runtime (ms)
`periscope_wait_ms_sum`	counter	Cumulative wait time (ms)
`periscope_queue_pending`	gauge	Jobs ready to process (live from driver)
`periscope_queue_delayed`	gauge	Jobs scheduled for the future
`periscope_queue_reserved`	gauge	Jobs currently claimed by a worker
`periscope_workers{status}`	gauge	Worker counts by status
`periscope_jobs_current{status}`	gauge	Monitored jobs by current status

Alerts

Three rules ship in the box:

failure_spike — more than N failed jobs in M minutes
long_wait — average wait exceeds a threshold
stale_worker — any worker has missed its heartbeat window

Each rule has a per-rule cooldown to prevent flooding. Configure thresholds in config/periscope.php and wire channels with env vars:

PERISCOPE_ALERT_CHANNELS=mail,slack,webhook
PERISCOPE_ALERT_MAIL=ops@example.com
PERISCOPE_ALERT_SLACK_WEBHOOK=https://hooks.slack.com/services/...
PERISCOPE_ALERT_WEBHOOK_URL=https://your-app.test/webhooks/periscope

Webhook payload shape:

{
    "key": "failure_spike",
    "title": "Queue failure spike",
    "message": "23 job(s) failed in the last 5 minutes (threshold: 10).",
    "severity": "error",
    "context": {"count": 23, "minutes": 5, "threshold": 10},
    "fired_at": "2026-04-17T20:30:00+00:00",
    "source": "periscope"
}

Schedule periscope:alerts:check every few minutes to evaluate the rules.

Batches

Periscope reads Laravel's native job_batches table, so there's no extra setup beyond running Laravel's own php artisan make:queue-batches-table + migration. The Batches page shows:

live progress bar (completed / total)
pending and failed counts
cancel button for in-flight batches

Any job that uses the Batchable trait and is dispatched via Bus::batch([...]) appears automatically.

Scheduled commands

Periscope subscribes to Laravel's scheduler events (ScheduledTaskStarting, Finished, Failed, Skipped) so every run of Schedule::command(...) is recorded with its runtime, exit status, and cron expression. The Schedules page shows the last N runs with failure messages for diagnosing cron issues.

No configuration needed — if your app uses the Laravel scheduler, it just works.

Performance percentiles

The Performance page computes p50 / p95 / p99 of both runtime and wait time for every queue that had completed jobs in the selected window (1 hour, 6 hours, 24 hours, or 7 days). Percentiles are calculated in PHP from a sorted sample so they work against every supported queue driver without needing database-specific percentile functions.

Exception grouping

The Exceptions page aggregates failures by exception_class + message. Click any row to drill into the /exceptions/show page, which lists every occurrence in the window, the affected jobs, and a sample stack trace you can click through.

Alert history

Every fired alert is persisted to the periscope_alerts table so you can audit what rules triggered, when, and which channels received them. The Alerts page lists all firings and lets you dismiss rows you've triaged.

Commands

Command	Purpose
`periscope:install`	Publish config, migrations, and compiled assets
`periscope:supervise {connection}`	Run a single `queue:work` with heartbeat reporting
`periscope:start`	Boot all supervisors from config (respawns children, handles SIGTERM)
`periscope:pause`	Stop spawning new workers; drain running ones
`periscope:continue`	Resume after a pause
`periscope:terminate`	Signal the master to shut down
`periscope:workers:sweep`	Mark workers stale past their heartbeat window
`periscope:snapshot`	Roll minute metrics into hourly buckets
`periscope:prune`	Delete old jobs and metrics per retention config
`periscope:alerts:check`	Evaluate alert rules and dispatch notifications

Run any command with --help for full flag reference.

Screenshots

Click to expand

Job detail — attempts timeline, memory, tags, payload

Jobs — filter by status, queue, tag, or search

Exceptions — grouped by class + message

Failed jobs — search, bulk retry / forget

Alerts — history of every fired rule

Schedules — every scheduled command run

Batches — Laravel batches with live progress

Performance — p50 / p95 / p99 per queue

Workers — live heartbeats

Queues — live driver sizes

Testing

composer install
./vendor/bin/pest

The suite uses Orchestra Testbench with in-memory SQLite. CI runs the full matrix of PHP 8.2 / 8.3 / 8.4 × Laravel 11 / 12 / 13 on every push.

Contributing

Bug reports and pull requests are welcome. Please run ./vendor/bin/pint and ./vendor/bin/pest before opening a PR.

Security issues: please email maherelgamil@gmail.com rather than filing a public issue.

Credits

Maher ElGamil
All contributors

License

The MIT License (MIT). See LICENSE for the full text.

maherelgamil / periscope

Maintainers

Package info

Statistics

Security