ashiqfardus / horizon-running-jobs
Monitor currently running jobs in Laravel Horizon for distributed systems
Package info
github.com/ashiqfardus/laravel-horizon-running-jobs
pkg:composer/ashiqfardus/horizon-running-jobs
Requires
- php: ^8.1 || ^8.2 || ^8.3 || ^8.4 || ^8.5
- illuminate/console: ^9.0 || ^10.0 || ^11.0 || ^12.0 || ^13.0
- illuminate/redis: ^9.0 || ^10.0 || ^11.0 || ^12.0 || ^13.0
- illuminate/support: ^9.0 || ^10.0 || ^11.0 || ^12.0 || ^13.0
- laravel/horizon: ^5.0 || ^6.0
Requires (Dev)
- orchestra/testbench: ^7.0 || ^8.0 || ^9.0 || ^10.0 || ^11.0
- phpunit/phpunit: ^9.0 || ^10.0 || ^11.0 || ^12.0 || ^13.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
See what's currently running in Laravel Horizon — across one server or many — and act on stuck jobs without leaving the dashboard.
Horizon's own UI shows pending, completed, and failed jobs but treats "running" as a black box. This package fills that gap with a Blade dashboard, a CLI suite, and an HTTP API. It works on a single application or on any number of instances sharing a Redis. Reserved jobs whose worker died (orphans), reservations that expired without cleanup (zombies), and supervisors that have stopped heartbeating (stale) are all surfaced and recoverable.
Table of contents
- What you get
- Requirements
- Installation
- Setup
- Concepts: running, zombie, orphan, stale
- Browser dashboard
- CLI commands
- HTTP API
- Securing access
- Configuration reference
- Using the facade
- How it works internally
- Upgrading from v1.0
- Testing
- Contributing
What you get
| Surface | What it shows / does |
|---|---|
/horizon/queue-monitor |
Standalone Blade dashboard — health banner, supervisor table, queue depths, running jobs with orphan/zombie badges, inline release buttons. Auto-refreshes. |
<x-horizon-running-jobs::*> |
Five composable Blade components (dashboard, diagnose-banner, supervisors-panel, queues-panel, running-jobs-table) you can drop into your own admin pages. |
horizon:running-jobs |
List currently-running jobs. Filter by queue, server, orphan-only. --watch for live refresh. --stats for aggregates. |
horizon:queues |
Per-queue depth: pending / reserved / delayed / total. |
horizon:supervisors |
Every Horizon supervisor + master process across the deployment, with stale flagging. |
horizon:diagnose |
One-shot health check across supervisors, jobs, and queue depths. Exits non-zero on failure — drop straight into cron. |
horizon:release |
Recover stuck reserved jobs by ID, or all orphans / zombies that have run past their timeout. Atomic. Confirms before applying. |
GET /api/horizon/* |
JSON endpoints for everything above (auth-gated, throttled). |
Requirements
| Component | Versions |
|---|---|
| PHP | 8.1, 8.2, 8.3, 8.4, 8.5 |
| Laravel | 9.x, 10.x, 11.x, 12.x, 13.x |
| Horizon | 5.x |
| Redis | 6.0+, with the phpredis extension or predis |
Composer resolves the right Laravel version for your PHP automatically. Laravel 13 requires PHP 8.3+; Laravel 11/12 require PHP 8.2+.
The test suite runs against the oldest and newest of each: PHP 8.1 with Laravel 9.0 and Horizon 5.8, up to PHP 8.5 with Laravel 13 and Horizon 5.50, on both Redis clients. Horizon 6 has not been released yet.
Installation
composer require ashiqfardus/horizon-running-jobs
Publish the config (optional — defaults are fine for most apps):
php artisan vendor:publish --tag=horizon-running-jobs-config
That's it. The dashboard at /horizon/queue-monitor, all CLI commands, and the HTTP API are wired up automatically. In a local or testing environment they're open; in any other environment they require an auth callback before responding.
Optional publishables
# Fork the Blade views to customize markup / structure php artisan vendor:publish --tag=horizon-running-jobs-views # Publish the CSS to serve from your own public directory php artisan vendor:publish --tag=horizon-running-jobs-css
Setup
Single server (default)
Nothing to configure. The package reads the Redis connection Horizon is using and surfaces everything reserved, regardless of which worker reserved it.
Distributed (multiple instances sharing one Redis)
Set distributed => true in config/horizon-running-jobs.php. Each instance will only see the jobs its own Horizon workers are running (see below); pass --all (CLI) or ?all=true (HTTP) to see everything across the cluster.
This applies to any topology where more than one Laravel instance points at the same Redis: multiple machines, containers / pods, even multiple instances on a single host. The discriminator is shared Redis, not multiple servers.
How the package identifies "this instance" depends on your config/horizon.php:
Auto-detect (works when this environment's first supervisor key is gethostname()):
// config/horizon.php 'environments' => [ 'production' => [ gethostname() => [ 'connection' => 'redis', 'queue' => ['default'], ], ], ],
The identifier is the first supervisor key under environments.<APP_ENV>. defaults is only consulted when that block is empty, and gethostname() itself only when there are no supervisors at all. Horizon's stock config defines supervisor-1 under each environment, which resolves to the same identifier on every instance.
Static names (containers, multi-tenant, anywhere gethostname() isn't unique):
// config/horizon.php 'defaults' => [ 'supervisor-01' => [...], 'supervisor-02' => [...], ],
// config/horizon-running-jobs.php 'server_identifier' => env('HORIZON_SUPERVISOR_NAME'),
# In each instance's .env
HORIZON_SUPERVISOR_NAME=supervisor-01
How a job is matched to its server
When a Horizon worker starts a job, the package records which supervisor runs it and when it started: one short Redis key per running job, removed when the job finishes or fails (see track_workers). The Server column, distributed filtering and orphan detection all use that record, so they are right however your jobs are dispatched: from a web node, a scheduler, another app, or the worker itself. Orphan detection compares the exact supervisor name, so hosts that share a supervisor key (Horizon's stock supervisor-1) cannot vouch for each other.
Workers start writing these records once they run this version, after php artisan horizon:terminate. Jobs without a record (started before that, or with track_workers off) fall back to a server:<identifier> tag on the job.
Optional: tag your jobs with their server (TracksServer trait)
The tag is the fallback for jobs without a worker record. Horizon computes tags when a job is dispatched, so the tag names the instance that dispatched the job. That is only the right server when the dispatching instance also runs the job, or when all instances share one identifier. Without a record and without a tag, the Server column shows unknown and the job is never reported as orphaned.
To add the tag, use the trait:
use Ashiqfardus\HorizonRunningJobs\Traits\TracksServer; class ProcessOrder implements ShouldQueue { use Dispatchable, InteractsWithQueue, Queueable, SerializesModels; use TracksServer; }
The trait's tags() returns server:<identifier>, environment:<env> and type:<class>. Once a job returns any tags of its own, Horizon no longer adds its automatic model tags (App\Models\Order:42); add those to your own tags() if you search by them.
Jobs that define their own tags(). A method on the class replaces the trait's method, so the server tag is not added for you. Merge serverTags() into your list:
public function tags(): array { return ['order:' . $this->order->id, ...$this->serverTags()]; }
Second fallback. Calling $this->initializeServerTracking() in the constructor also stores the identifier on the job as a supervisor_id property, read when a job has neither a worker record nor a server tag.
Concepts: running, zombie, orphan, stale
Four states. Read these once and the dashboard makes immediate sense.
running — normal
A job is in queues:<q>:reserved (Redis sorted set), its expiry score is in the future, and the supervisor that reserved it is alive and heartbeating. The worker is processing it.
zombie — reservation expired
The reserved-set entry's score is in the past. The reservation timed out without the worker either completing the job or releasing it cleanly. Causes:
- The worker process died (OOM, SIGKILL) before finishing
- The job exceeded the queue's
retry_afterwindow - Horizon hasn't reaped the entry yet
A zombie blocks its queue slot until something releases or removes it. With retry_after => null on the queue connection, reservations never expire, so no job is ever a zombie.
orphan — worker is gone
The supervisor running the job (from its worker record, else its server: tag) is neither heartbeating nor managed by a live Horizon master any more. Usually the worker that was running the job is gone and no one will finish it.
Not always, though. During horizon:terminate (every deploy), supervisors deregister first and their workers then finish the job in hand, so those jobs show as orphans until they complete. That is why an orphan is only offered for release once it has run past its timeout (see Recovery).
A job can be both zombie and orphan (⚠ orphan + zombie).
stale — supervisor
Different layer. A supervisor (worker process manager) entry exists in Redis but its last heartbeat is older than Horizon's own 29-second alive window plus a small grace window (14 seconds plus grace for a master). A running Horizon master removes entries after 14 seconds of silence, so a stale row means no master is running on this Redis any more: Horizon was killed, the host died, or it lost its connection to Redis. A stale supervisor causes orphans on jobs it reserved.
Relationships
Healthy ──────────────────────────┐
│ │
▼ ▼
Worker dies ── creates ▶ zombie Supervisor dies ── creates ▶ stale
│
▼
Jobs reserved by it become ▶ orphan
Recovery: zombies and orphans are recovered by releasing them — moving them back to the pending list so a healthy worker can pick them up. Use the dashboard's inline release button or the CLI command horizon:release.
Releasing a job a worker is still running makes it run twice, so release is only offered once the job has run past its timeout plus a margin (release_margin_seconds, default 10). A Laravel worker stops a job when it hits its timeout, so by then a healthy worker is done with it. On top of that:
- an orphan must have a worker record, so its start time, timeout and supervisor are known rather than inferred;
- an orphan without a record is released only once its reservation has also expired, which is when Laravel would re-queue it anyway;
- a zombie (expired reservation) is released once past its timeout.
The timeout is the one the worker enforces: the job's own $timeout, else the --timeout its Horizon supervisor started it with (Horizon's default is 60). Until release is possible the dashboard shows when it will be. A job with no timeout (0) is never released in bulk; release it by UUID if you are sure it is stuck.
The timeout is enforced with a signal, which a job blocked inside some C extension calls (a socket read with no timeout of its own) only handles once the call returns. Give such calls their own timeouts.
Browser dashboard
Standalone page
Visit /horizon/queue-monitor in your app. Auth is gated by the same callback as the JSON API (see below).
Layout:
- Top banner — overall health (PASS / WARN / FAIL) plus per-check findings as a stacked list
- Supervisors panel — every supervisor in Horizon's registry, with status, PID, queues, time since last heartbeat
- Queue depth panel — pending / reserved / delayed counts per queue
- Running jobs table — orphan and zombie badges (with icon prefixes for color-blind a11y), an inline
releasebutton on orphan / zombie rows that have run past their timeout (the others show when release becomes available), and a "release N stuck" bulk action covering exactly those rows
Interactivity:
- Click any row in running jobs to drill down into the full job payload (class, UUID, queue, server, status, timing, attempts, timeout, tags)
- Pause auto-refresh per panel — every panel header has a ⏸/▶ toggle so you can read a row without it disappearing on the next poll
- Custom confirm modal for release actions (showing job summary) — no browser-native
confirm()dialog - Toast feedback on every release with success / failure count
Polling: each panel polls a per-component endpoint on its own interval (banner 5s, supervisors 5s, queues 5s, jobs 3s). No page reload needed; tables re-render in place with a brief fade. Honors prefers-reduced-motion.
Disable the route entirely:
// config/horizon-running-jobs.php 'ui' => [ 'enabled' => false, ],
Embedding panels in your own dashboard
Each panel is an anonymous Blade component:
{{-- Full dashboard --}} <x-horizon-running-jobs::dashboard /> {{-- Or compose individually --}} <x-horizon-running-jobs::diagnose-banner /> <x-horizon-running-jobs::supervisors-panel /> <x-horizon-running-jobs::queues-panel /> <x-horizon-running-jobs::running-jobs-table :poll="3000" :allow-release="true" /> {{-- Filtered to orphans only --}} <x-horizon-running-jobs::running-jobs-table :orphaned-only="true" />
Component props:
| Component | Props |
|---|---|
dashboard |
:poll (default 5000), :jobs-poll (default 3000) |
diagnose-banner |
:poll (default 5000) |
supervisors-panel |
:poll (default 5000) |
queues-panel |
:poll (default 5000) |
running-jobs-table |
:poll (default 3000), :allow-release (default true), :orphaned-only (default false) |
Pass :poll="0" to disable a panel's auto-refresh.
For panels embedded in your page (not the standalone dashboard), the host page must also load:
- The package CSS, served at
/horizon/queue-monitor/assets/css, or published viavendor:publish --tag=horizon-running-jobs-css - Alpine.js (Laravel's default for Blade interactivity)
- A
<meta name="csrf-token" content="{{ csrf_token() }}">tag if:allow-releaseis enabled — the release POST is CSRF-protected
The factory functions Alpine needs (hrjPanel, hrjReleaseButton) are inlined in the standalone dashboard. If you're embedding components in your own page and want auto-refresh + release to work, copy the inline <script> block from vendor/ashiqfardus/horizon-running-jobs/resources/views/dashboard.blade.php into your layout, or include the published JS.
Theming
The package CSS is fully scoped under .hrj — it cannot leak into your styles. All colors are CSS variables — override any of them in your own stylesheet to retheme:
.hrj { --hrj-color-pass: #00b8a9; --hrj-color-warn: #ffae00; --hrj-color-fail: #ff5b5b; --hrj-color-orphan: #ff7a45; --hrj-color-zombie: #b388ff; --hrj-bg: #ffffff; --hrj-text: #1a1a1a; --hrj-border: #e5e5e5; /* ... see resources/css/horizon-running-jobs.css for the full list */ }
Dark mode is auto-detected via prefers-color-scheme. Force light by adding class="hrj hrj--light" on the wrapper.
CLI commands
Every command supports --json for scripting and a -h help flag.
horizon:running-jobs
List jobs currently in the reserved set.
# Default — current server's jobs (or all jobs in non-distributed mode) php artisan horizon:running-jobs # All servers across the cluster php artisan horizon:running-jobs --all # Specific queues php artisan horizon:running-jobs --queue=emails --queue=reports # Limit display php artisan horizon:running-jobs --limit=50 # Only orphans (worker process is gone) php artisan horizon:running-jobs --orphaned # Live-refresh (Ctrl-C to exit) php artisan horizon:running-jobs --watch php artisan horizon:running-jobs --watch=5 # custom interval (seconds) # Aggregate stats php artisan horizon:running-jobs --stats # JSON for scripting php artisan horizon:running-jobs --json
Sample output:
🔍 Scanning queues: default, emails, reports
📍 Current server: app-server-01
+----------+--------------------+----------+----------------+----------+----------+----------+----------+
| ID | Job | Queue | Server | Status | Started | Duration | Attempts |
+----------+--------------------+----------+----------------+----------+----------+----------+----------+
| 4b5ecc82 | App\Jobs\Process… | default | app-server-01 | running | 14:30:15 | 2m 34s | 1 |
| 8a2b3c4d | App\Jobs\StuckJob | reports | app-server-01 | ⚠ orphan | 14:31:42 | 12m 08s | 1 |
+----------+--------------------+----------+----------------+----------+----------+----------+----------+
✓ Found 2 running job(s)
⚠️ 1 orphan job(s) detected (worker process is no longer registered)
horizon:queues
Per-queue depth:
php artisan horizon:queues php artisan horizon:queues --queue=emails --queue=reports php artisan horizon:queues --json php artisan horizon:queues --watch
+---------+---------+----------+---------+-------+
| Queue | Pending | Reserved | Delayed | Total |
+---------+---------+----------+---------+-------+
| default | 12 | 3 | 0 | 15 |
| emails | 4 | 1 | 2 | 7 |
| reports | 0 | 0 | 0 | 0 |
+---------+---------+----------+---------+-------+
| TOTAL | 16 | 4 | 2 | 22 |
+---------+---------+----------+---------+-------+
Columns:
- Pending — jobs in
queues:<name>(Redis list), waiting to be picked up - Reserved — jobs in
queues:<name>:reserved(sorted set), currently being processed (or stuck) - Delayed — jobs in
queues:<name>:delayed(sorted set), scheduled to fire later - Total — sum of the three
horizon:supervisors
Every supervisor and master process Horizon has registered in Redis, across the whole deployment:
php artisan horizon:supervisors
php artisan horizon:supervisors --masters # include master table
php artisan horizon:supervisors --json
php artisan horizon:supervisors --watch
+---------------------------+---------+------+------------------------+-------+-----------+
| Name | Status | PID | Queues | Procs | Heartbeat |
+---------------------------+---------+------+------------------------+-------+-----------+
| app-01-x7Kp:supervisor-01 | running | 8298 | default,emails,reports | 3 | 0s ago |
| app-02-Qm3d:supervisor-01 | running | 4521 | default,emails,reports | 3 | 1s ago |
+---------------------------+---------+------+------------------------+-------+-----------+
Names are Horizon's own: <master name>:<supervisor key>. The Heartbeat column is the time since the supervisor last reported to Redis, normally a second or two. A row is flagged ⚠ stale once it has been silent for more than 29 seconds plus the grace window (default 5s, see config). A running Horizon master removes silent entries after 14 seconds, so you only see stale rows when no master is running on this Redis any more; the command then warns that supervisors stopped heartbeating.
horizon:diagnose
Unified health check. Exits 0 on pass-or-warn, exits non-zero on hard failure (e.g. no live supervisor at all). Drop straight into cron:
php artisan horizon:diagnose php artisan horizon:diagnose --json
🔍 Horizon Health Diagnosis
✓ horizon.supervisors 2 supervisor(s) running
⚠ jobs.orphaned 1 orphan job(s) — see `horizon:running-jobs --orphaned`
✓ jobs.zombies 0 zombie jobs
✓ jobs.malformed 0 malformed entries
✓ queues.depths highest pending: emails (47), totals: pending=58 reserved=4 delayed=2
Status: WARN
Checks:
| Name | Pass | Warn | Fail |
|---|---|---|---|
horizon.supervisors |
At least 1 live, none stale | Some stale, OR all stale (Horizon master may have died) | ZSET empty (Horizon never started or all entries reaped) |
jobs.orphaned |
0 orphans | ≥1 orphan | — |
jobs.zombies |
0 zombies | ≥1 zombie | — |
jobs.malformed |
0 dropped | ≥1 dropped (see logs) | — |
queues.depths |
always pass (informational) | — | — |
horizon:release
Move stuck reserved jobs back to the pending list. The only mutating command in the suite. Atomic per job: one Redis script removes the job from the reserved set and pushes it to pending only if it was still reserved, so a job that finished in the meantime is not run again.
# Release a single job by UUID php artisan horizon:release abc-123-def-456 # Release every orphaned job that has run past its timeout php artisan horizon:release --orphaned # Release every zombie (expired) job past its timeout, scoped to a specific queue php artisan horizon:release --zombie --queue=reports # Both at once php artisan horizon:release --orphaned --zombie # Preview without modifying Redis php artisan horizon:release --orphaned --dry-run # Skip the confirmation prompt (for cron / scripts) php artisan horizon:release --orphaned --force
Behavior:
- Released jobs go to the front of the pending list (LPUSH) so a worker picks them up promptly
- Each release is logged via
Log::infowith the job UUID, queue, and reason — audit trail for ops --orphanedand--zombieonly pick jobs that have run past their timeout (see Recovery); they can be combined- A positional UUID releases that job whatever its state, and warns when a worker may still be running it. It cannot be combined with
--orphaned/--zombie --orphanedstops with an error, releasing nothing, if the live supervisors cannot be read from Redis- The interactive confirm shows a full table of jobs that will be released before applying
--queue=repeats to scope to specific queues
--watch mode
The list-style commands (horizon:running-jobs, horizon:queues, horizon:supervisors) accept a --watch[=seconds] flag that re-renders on a loop, like top:
php artisan horizon:running-jobs --watch # 3s default php artisan horizon:queues --watch=10 # 10s interval
Press Ctrl-C to exit. Ignored when combined with --json.
--json mode
Every command emits machine-readable JSON with --json:
php artisan horizon:queues --json | jq '.totals.pending' php artisan horizon:diagnose --json | jq '.overall_status'
horizon:diagnose --json is particularly useful for monitoring/alerting:
if [ "$(php artisan horizon:diagnose --json | jq -r .overall_status)" = "fail" ]; then page-oncall "Horizon is down" fi
HTTP API
Auth-gated by the same callback as the dashboard. Throttled to 60 requests/minute per caller by default.
GET /api/horizon/running-jobs
GET /api/horizon/running-jobs GET /api/horizon/running-jobs?all=true GET /api/horizon/running-jobs?queues=emails,reports GET /api/horizon/running-jobs?orphaned=true GET /api/horizon/running-jobs?server_identifier=supervisor-02 # another instance's jobs (distributed mode)
Sample response:
{
"success": true,
"server_identifier": "app-server-01",
"hostname": "app-server-01",
"timestamp": "2026-04-25T10:30:00+00:00",
"queues_monitored": ["default", "emails", "reports"],
"running_jobs_count": 1,
"total_count": 1,
"dropped_count": 0,
"orphan_count": 0,
"orphaned_only": false,
"jobs": [
{
"job_id": "4b5ecc82-07a7-40db-97db-bfab5ac5c500",
"job_class": "App\\Jobs\\ProcessOrder",
"queue": "default",
"server": "app-server-01",
"status": "running",
"is_orphaned": false,
"start_time": "2026-04-25T10:27:26+00:00",
"start_timestamp": 1777112846,
"running_for_seconds": 154,
"running_for_formatted": "2m 34s",
"attempts": 1,
"timeout": 120,
"tags": ["server:app-server-01", "environment:production"]
}
],
"warnings": []
}
Response field reference:
| Field | Meaning |
|---|---|
server_identifier |
the identifier the request was scoped to: the ?server_identifier= value if given (?hostname= is the older name and still works), otherwise this instance's server identifier. With Horizon's stock config that is the supervisor key (supervisor-1), not the machine's host name |
hostname |
deprecated alias of server_identifier, kept for existing clients |
running_jobs_count |
jobs returned in this payload (may be limited by max_jobs) |
total_count |
total reserved-set entries found before truncation |
dropped_count |
malformed reserved-set entries skipped; each is logged via Log::warning |
orphan_count |
jobs whose supervisor is no longer alive |
orphaned_only |
echoes whether ?orphaned=true was active for this request |
jobs[].status |
"running" (reservation valid) or "zombie" (reservation expired) |
jobs[].server |
the server identifier (supervisor key) running the job, from its worker record, else its server: tag; unknown when neither exists |
jobs[].supervisor |
the exact Horizon supervisor running the job (<master>:<key>), or null without a worker record |
jobs[].is_orphaned |
true when that supervisor is no longer alive |
jobs[].is_releasable |
true when the job is offered for release: an orphan with a worker record, or an expired job, that has run past its timeout plus release_margin_seconds (see Recovery) |
jobs[].releasable_at |
Unix time from which the job can be released; null when it never can (no timeout, or no worker record and reservations never expire) |
jobs[].start_time / start_timestamp |
when the job started: from its worker record, else its reservation time (not the Redis expiry score) |
warnings[] |
human-readable summary lines — long-running, zombie count, orphan count, dropped count |
GET /api/horizon/running-jobs/stats
Aggregate stats:
{
"success": true,
"timestamp": "2026-04-25T10:30:00+00:00",
"stats": {
"total_running": 5,
"by_server": {"app-01": 3, "app-02": 2},
"by_queue": {"default": 4, "reports": 1},
"by_job_class": {"App\\Jobs\\ProcessOrder": 5},
"by_status": {"running": 4, "zombie": 1},
"by_orphan_status": {"healthy": 4, "orphaned": 1},
"dropped_count": 0,
"orphan_count": 1,
"longest_running": { /* job object */ },
"warnings": []
}
}
GET /api/horizon/queues
GET /api/horizon/queues
GET /api/horizon/queues?queues=emails,reports
{
"success": true,
"inspected_at": 1777112846,
"queue_count": 3,
"totals": {"pending": 16, "reserved": 4, "delayed": 2, "total": 22},
"queues": [
{"queue": "default", "pending": 12, "reserved": 3, "delayed": 0, "total": 15},
{"queue": "emails", "pending": 4, "reserved": 1, "delayed": 2, "total": 7},
{"queue": "reports", "pending": 0, "reserved": 0, "delayed": 0, "total": 0}
]
}
GET /api/horizon/supervisors
{
"success": true,
"inspected_at": 1777112846,
"supervisor_count": 2,
"master_count": 1,
"stale_supervisor_count": 0,
"supervisors": [
{
"name": "app-01-x7Kp:supervisor-01",
"status": "running",
"master": "app-01-x7Kp",
"pid": 8298,
"queues": ["default", "emails", "reports"],
"process_count": 3,
"processes": {"redis:default": 1, "redis:emails": 1, "redis:reports": 1},
"last_heartbeat_at": 1777112845,
"seconds_since_heartbeat": 1,
"expires_at": 1777112874,
"seconds_until_expiry": 28,
"is_stale": false
}
],
"masters": [
{
"name": "app-01-x7Kp",
"status": "running",
"environment": "production",
"pid": 8283,
"supervisor_count": 1,
"last_heartbeat_at": 1777112846,
"seconds_since_heartbeat": 0,
"expires_at": 1777112860,
"seconds_until_expiry": 14,
"is_stale": false
}
]
}
| Field | Meaning |
|---|---|
last_heartbeat_at / seconds_since_heartbeat |
when the process last reported to Redis |
expires_at / seconds_until_expiry |
when Horizon itself stops treating the process as alive: last heartbeat + 29s for a supervisor, + 14s for a master |
is_stale |
true once the process has been silent past expires_at plus supervisor_stale_grace_seconds |
Validation
Endpoints accepting ?queues= enforce:
- Each name matches
[A-Za-z0-9_:.-]+ - At most 20 names per request
- Invalid input →
422 Unprocessable Entity
Securing access
The package is safe by default:
- In
localandtestingenvironments — open. Zero-friction development. - Anywhere else — denied with a 403 unless you register an auth callback.
- Throttled to 60 requests/minute per caller out of the box.
Production: register an auth callback
In your AppServiceProvider::boot():
use Ashiqfardus\HorizonRunningJobs\HorizonRunningJobs; public function boot(): void { HorizonRunningJobs::auth(function ($request) { return $request->user()?->is_admin === true; }); }
The closure receives the incoming Illuminate\Http\Request. Return true to allow, false to deny. Works with whatever auth scheme you have — Sanctum, Passport, sessions, custom.
$request->user() is only populated when the route group runs middleware that authenticates the request. The dashboard's default web group does that for session logins. The JSON API's default ['api', 'throttle:60,1'] does not, so a callback that relies on $request->user() returns 403 there until you add your guard (for example auth:sanctum, see Layering).
If you forget to register the callback in production, the 403 response includes a copy-paste example showing exactly how to fix it.
Apps that authenticate with tokens (JWT, Sanctum personal access tokens)
$request->user() is only set when the request carries your app's credentials. A browser opening /horizon/queue-monitor sends no bearer token, so in a token-only app the callback above sees no user and the dashboard returns 403 for everyone.
One pattern that works is HTTP Basic auth in front of the package routes, with the callback accepting only requests that middleware has passed:
// config/services.php 'queue_monitor' => [ 'user' => env('QUEUE_MONITOR_USER'), 'password' => env('QUEUE_MONITOR_PASSWORD'), ],
// app/Http/Middleware/QueueMonitorBasicAuth.php namespace App\Http\Middleware; use Closure; use Illuminate\Http\Request; use Illuminate\Support\Facades\RateLimiter; class QueueMonitorBasicAuth { public function handle(Request $request, Closure $next) { $user = (string) config('services.queue_monitor.user'); $password = (string) config('services.queue_monitor.password'); $attempts = 'queue-monitor-auth:' . $request->ip(); if (RateLimiter::tooManyAttempts($attempts, 5)) { return response('Too many attempts', 429); } if ($password === '' || ! hash_equals($user, (string) $request->getUser()) || ! hash_equals($password, (string) $request->getPassword())) { // Count wrong credentials only, not the browser's first // credential-less request. if ($request->getUser() !== null) { RateLimiter::hit($attempts, 60); } return response('Unauthorized', 401, ['WWW-Authenticate' => 'Basic realm="Queue monitor"']); } $request->attributes->set('queue_monitor_authenticated', true); return $next($request); } }
// config/horizon-running-jobs.php 'ui' => [ 'middleware' => ['web', \App\Http\Middleware\QueueMonitorBasicAuth::class], ], 'routes' => [ 'middleware' => ['api', 'throttle:60,1', \App\Http\Middleware\QueueMonitorBasicAuth::class], ],
// AppServiceProvider::boot() HorizonRunningJobs::auth( fn ($request) => $request->attributes->get('queue_monitor_authenticated') === true );
The middleware runs in every environment, local included, and locks everyone out while the password is unset. Serve the dashboard over HTTPS only: Basic auth sends the password with every request.
Layering with auth middleware (optional)
Add additional middleware to defend in depth:
// config/horizon-running-jobs.php 'routes' => [ 'middleware' => ['api', 'throttle:60,1', 'auth:sanctum'], ],
The bundled Authorize middleware runs after whatever you configure here, so you get both — middleware AND callback must pass.
Disable the routes entirely
If you'd rather wire your own controllers / Gate-based authorization:
'routes' => [ 'enabled' => false, ], 'ui' => [ 'enabled' => false, ],
Configuration reference
Every config key, with default and meaning. From config/horizon-running-jobs.php:
| Key | Default | Meaning |
|---|---|---|
distributed |
false |
Enable when more than one Laravel instance shares one Redis. Each instance only sees its own jobs unless --all / ?all=true is passed. |
server_identifier |
null |
How this instance identifies itself in distributed mode. null = auto-detect: the first supervisor key of the Horizon environment (horizon.env, else APP_ENV; wildcard keys such as production* match the way Horizon matches them), then the first under horizon.defaults, then gethostname(). Set it explicitly for static names, containers, etc. |
queues |
null |
Default queues to monitor. null = auto-detect from config('horizon.defaults.*.queue'). Pass ['default', 'emails'] to pin. |
max_jobs |
1000 |
Hard cap on jobs returned in a single query. Prevents memory blowups on very deep reserved sets. |
long_running_threshold |
300 |
Seconds before a job's row is flagged as "long-running" in warnings. |
cache.enabled |
true |
Cache the running-jobs API responses (/running-jobs, /running-jobs/stats) and facade calls for cache.ttl seconds. The dashboard panels and the CLI always read live data. |
cache.ttl |
10 |
Cache duration in seconds. A job shorter than this can start and finish without appearing in an API response. |
cache.prefix |
'horizon_running_jobs' |
Cache key prefix. |
routes.enabled |
true |
Whether the JSON API routes are registered. |
routes.prefix |
'api' |
URL prefix for API routes. |
routes.middleware |
['api', 'throttle:60,1'] |
Middleware stack for API routes. The Authorize middleware is appended unconditionally. |
routes.uri |
'horizon/running-jobs' |
Path segment for the running-jobs endpoint. |
ui.enabled |
true |
Whether the Blade dashboard route is registered. |
ui.prefix |
'horizon/queue-monitor' |
URL prefix for the dashboard. |
ui.middleware |
['web'] |
Middleware stack for the dashboard. The Authorize middleware is appended unconditionally. web is required for sessions + CSRF on the release POST. |
redis_connection |
null |
Redis connection name. null = auto-detect from config('horizon.use'). |
retry_after |
null |
The queue's retry_after window, used for duration math. null = auto-detect: the queue connection your Horizon supervisors run on (connection in horizon.defaults / horizon.environments), then any redis-driver queue connection on Horizon's Redis connection, then 90 (the value in Laravel's stock config/queue.php). On the connection found, a missing key means 60 (the connectors' default) and null means reservations never expire, so no job is reported as a zombie. |
supervisor_stale_grace_seconds |
5 |
Extra margin on top of Horizon's own alive window (29s for a supervisor, 14s for a master) before a process is flagged stale and its jobs orphaned. It cannot extend past Horizon's own cleanup: a running master removes an entry after 14s of silence. |
track_workers |
true |
Have Horizon workers record which supervisor runs each job (one Redis write when a job starts, one when it ends). Used for the Server column, distributed filtering, orphan detection and start times. false falls back to dispatch-time tags. |
release_margin_seconds |
10 |
Seconds past a job's timeout before it is offered for release. Absorbs clock differences between worker hosts and the one viewing the dashboard. |
Using the facade
use Ashiqfardus\HorizonRunningJobs\Facades\RunningJobs; // Current server only $result = RunningJobs::getRunningJobs(); // All servers $result = RunningJobs::getRunningJobs(null, true); // Specific queues $result = RunningJobs::getRunningJobs(null, false, ['emails', 'reports']); // Filter to orphans only $result = RunningJobs::getRunningJobs(null, true, null, $orphanedOnly = true); // Aggregate stats $stats = RunningJobs::getStats(); // Skip the response cache for a live read $result = RunningJobs::withoutCache(fn ($manager) => $manager->getRunningJobs(null, true));
For releasing jobs programmatically:
use Ashiqfardus\HorizonRunningJobs\JobReleaser; $releaser = app(JobReleaser::class); // Find what's releasable (read-only) $found = $releaser->findReleasable(['orphaned' => true, 'queues' => ['reports']]); // Release them (atomic per-job) $count = $releaser->release($found);
How it works internally
Laravel's Redis queue stores jobs in three keys per queue:
| Key | Type | Contains |
|---|---|---|
queues:{q} |
LIST | Pending jobs (workers LPOP from here) |
queues:{q}:reserved |
ZSET | Currently-reserved jobs (score = expiry timestamp) |
queues:{q}:delayed |
ZSET | Scheduled / delayed jobs (score = release timestamp) |
This package reads all three. For supervisors / health, it also reads Horizon's own keys on the horizon Redis connection:
| Key | Type | Contains |
|---|---|---|
supervisors |
ZSET | Supervisor names (score = time of last heartbeat; Horizon treats one as alive for 29s after it) |
masters |
ZSET | Master process names (score = time of last heartbeat; alive for 14s after it) |
supervisor:{name} |
HASH | Per-supervisor metadata (pid, queues, process counts) |
master:{name} |
HASH | Per-master metadata, including the supervisors it manages |
And it writes one key of its own, on the queue's Redis connection, while a job runs:
| Key | Type | Contains |
|---|---|---|
horizon-running-jobs:{workers}:<uuid> |
STRING | JSON {"supervisor": "<master>:<key>", "started_at": <unix>}, written by the worker when the job starts, deleted when it finishes or fails; expires after a day if the worker is killed. The {workers} hash tag keeps all of them on one Redis Cluster slot. |
Identifying which job belongs to which server
Three paths, in order:
- Worker record — the key above. Names the exact supervisor running the job; orphan detection matches it exactly.
- Tags — Horizon stores tags as part of the job payload, computed at dispatch. The package looks for
server:<name>and matches it against the key part of live supervisor names. supervisor_idproperty — fallback if no tag is set. The package extracts via regex (nounserialize).
The TracksServer trait adds the tag for you. If you have your own tags(), merge the trait's serverTags() into it, or return a server:<identifier> tag yourself.
Distributed mode
┌─────────────────┐
│ Redis Server │
└────────┬────────┘
│
┌──────────────┼──────────────┐
│ │ │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│ App A │ │ App B │ │ App C │
│ 5 jobs │ │ 3 jobs │ │ 7 jobs │
└─────────┘ └─────────┘ └─────────┘
Each instance can see its own jobs (default) or all jobs in the cluster (with --all / ?all=true).
Cache invalidation
The running-jobs API responses (/running-jobs, /running-jobs/stats) and facade calls cache for cache.ttl seconds (default 10) to prevent hammering Redis. The supervisors and queues endpoints are never cached. The dashboard panels and the CLI commands bypass the cache, so they show jobs shorter than the TTL; use RunningJobs::withoutCache() for the same in your own code. Cache keys embed an epoch counter; calling RunningJobs::clearCache() increments the epoch, invalidating every previously-cached response without needing wildcard deletes.
Upgrading from v1.0
v2.0 introduces several breaking changes plus a substantial feature set. Before upgrading:
Breaking changes
-
Production endpoints now deny by default. v1.0 left the routes wide open in any environment. v2.0 returns
403fromlocal/testing-other environments unless you register an auth callback. The 403 body includes a copy-paste example. See Securing access. -
RunningJobsManager::parseJobData()throwsRuntimeExceptionon malformed payloads (was: returnednull). Calling code that relied on the null return needs to wrap in try/catch or call from inside the manager which already handles it. -
response().jobs[*].start_time/start_timestampreflect the actual reservation time rather than the Redis expiry score. Charts that built duration math on the v1 values may need adjustment. -
Default route middleware adds
throttle:60,1. Callers exceeding 60 requests/minute now receive 429. -
PHP 8.0 dropped. Minimum is PHP 8.1.
Additive (no action needed)
- New CLI commands:
horizon:queues,horizon:supervisors,horizon:diagnose,horizon:release - New HTTP endpoints:
/api/horizon/queues,/api/horizon/supervisors - New Blade dashboard at
/horizon/queue-monitor+ composable components - New job fields:
is_orphaned,status("running"|"zombie") - New response fields:
orphan_count,dropped_count,orphaned_only --watchflag on list-style commands
Deprecated (still works, will be removed in v3.0)
- The standalone JS widget (
vendor:publish --tag=horizon-running-jobs-assets) and the bundled Vue component. Both only show running jobs and lack any of the v2 features. Migrate to the Blade dashboard.
Testing
composer test
Runs the full PHPUnit suite. No Redis required for unit + feature tests; integration tests skip themselves when Redis isn't reachable on 127.0.0.1:6379.
For end-to-end testing against a real Laravel app, there's a companion demo project at github.com/ashiqfardus/laravel-horizon-running-jobs-demo — a fresh Laravel 13 install with Horizon configured and a handful of dummy jobs (fast / medium / slow / flaky / memory-heavy / stuck) already wired up. Clone it as a sibling of this package directory and it'll resolve via Composer's path symlink:
git clone https://github.com/ashiqfardus/laravel-horizon-running-jobs-demo.git cd laravel-horizon-running-jobs-demo composer install cp .env.example .env && php artisan key:generate php artisan horizon # terminal 1 php artisan demo:dispatch-workload # terminal 2 — varied jobs across queues php artisan demo:simulate-orphan --count=2 # terminal 2 — flip to broken state php artisan horizon:running-jobs --orphaned # observe the orphans (flagged ~15s after the kill) php artisan horizon:release --orphaned # release them once past their timeout (~40s after dispatch)
The demo also serves the Blade dashboard at /horizon/queue-monitor.
Contributing
PRs welcome. Run composer test before submitting. Integration tests require Redis on 127.0.0.1:6379.
Security
Found a security issue? Email ashiqfardus@hotmail.com instead of using the public issue tracker.
Credits
License
MIT — see LICENSE.md.