Laravel supervisor dashboard at /queen

The Laravel panel shows what this application’s Queen supervisors are doing. It reads the state the PHP or Rust engine writes on its host, and the copy each engine can publish to the broker for web servers on other hosts. Its pages also read the broker for what the queues hold and how many jobs ran. It is off until you turn it on, and in production it lets nobody in until your application says who may.

QUEEN_DASHBOARD_ENABLED=true
QUEEN_DASHBOARD_PATH=queen

Open /queen. While the application defines no viewQueenDashboard Gate, the panel lets you in in the local and testing environments as long as queen.dashboard.allow_local is true; once the Gate is defined, it decides in every environment. Set dashboard.allow_local to false in config/queen.php to try the production path on your machine. Each sidebar section is its own page, so a reload or a shared link lands on the same view:

Each page refreshes itself every dashboard.refresh_seconds (5 s by default): a small packaged script fetches the page again and swaps only the header and the main region, so your scroll position and the sidebar stay put. Pause auto-refresh in the header stops it, and the browser remembers the choice. Refreshing waits while the tab is hidden, while text is selected or while a control you are using would be replaced, and it stops with a notice when the answer is no longer the panel (after the session expired, say). Without JavaScript the pages still work, reloading whole through a <noscript> refresh.

If Laravel has cached its routes and configuration, a change to the path, domain, enabled flag or middleware needs both caches rebuilt:

php artisan config:clear && php artisan route:clear
php artisan config:cache && php artisan route:cache

Authorize production access

Enabling the route is not enough in production: the panel denies everyone until the application defines the viewQueenDashboard Gate ability. Put your authentication in front of it:

// config/queen.php
'dashboard' => [
    'enabled' => env('QUEEN_DASHBOARD_ENABLED', false),
    'path' => env('QUEEN_DASHBOARD_PATH', 'queen'),
    'middleware' => ['web', 'auth'],
],

use Illuminate\Support\Facades\Gate;

Gate::define('viewQueenDashboard', function ($user): bool {
    return $user !== null && $user->canOperateQueues();
});

The package always keeps Laravel’s web middleware, even if you leave it out of the list, because the controls change state and must keep their session and CSRF protection. The same Gate guards the HTML pages, the JSON status and the controls, so a Gate that returns true for everyone hands any visitor the pause button. Define one only when another trusted layer in front of the panel has already authenticated and authorized the request. Put the panel behind the same network and identity controls as any other administration page.

What the panel shows

The overview and the supervisor cards show each master’s engine, host, PID, state, generation and heartbeat; whether its status is local or published by a supervisor on another host; its pools, queues and worker counts, the workers draining, and the restart and circuit state; and the last depth each pool sampled. When more than one running master autoscales the same queue and consumer group without coordinating, the panel warns: each master sizes its workers from the whole backlog, so together they can run more than max_processes. Coordinated replicas share one target and are not reported, and each coordinated pool shows its share of the replicas. Fixed pools (balance simple) do not follow the backlog and are not reported either.

Some things stay off the page on purpose. The read model returns no broker endpoint, bearer token, custom header, job payload or raw backend error. A broker endpoint appears as scheme, host and port, a credential as set or not set, and exception text only on the detail page of a failed job. A failed-job store the panel cannot read safely is shown as unavailable, never read without a bound.

What the panel controls

Three controls act on the whole local master:

Each form carries the exact supervisor instance_id, so a page left open across a deploy cannot pause or terminate the replacement master, and a second command never overwrites one still pending.

Your authentication middleware runs before the Gate, so an unauthenticated request may redirect or answer 401 instead, depending on the guard. The control TTL and the heartbeat timeout are the ones the running master published: a newly deployed configuration cannot reinterpret an old master’s liveness or replay an expired command. Restart the supervisor to change them.

In the queue now

The Workload page opens with one row per supervised queue: its consumer group, the jobs waiting for a worker, the jobs running now, and how long the oldest unfinished job has been in the queue, waiting or running (PHP client 1.9.0). It is a summary; the Queen dashboard lists the messages themselves.

The panel asks the broker only for partitions whose oldest unacknowledged job is more than a minute old, so a younger age reads under a minute. Ten minutes or more gets a warning badge, an hour a danger badge. A queue the broker does not answer for is marked Unavailable, and an age the broker could not report shows as a dash, never as under a minute. Only the Workload page reads these figures: one depth request per queue and one lag request per connection, in parallel, with the supervisor’s read_bearer_token when one is set, one attempt of at most five seconds, cached for five seconds in Laravel’s default cache store. The card shows at most 32 queues.

Set the address of the Queen dashboard and every row links to it: Open in console opens the queue’s page, /queues/{queue}, and the waiting and running numbers open its messages filtered to pending and processing (/messages?queue={queue}&status=pending). The queue name is URL-encoded, and every link opens in a new tab with rel="noopener noreferrer".

QUEEN_DASHBOARD_CONSOLE_URL=https://queen.example.com

That is the address you open the Queen dashboard at: the broker’s own port, 6632, or the port of its embedded proxy when that is your front door. The value must be an http or https URL without user info, query or fragment; a path is kept, for a dashboard behind a prefix. One address serves one broker, so when the supervised queues use more than one connection, the card shows no links and says why. An invalid value is reported to the application’s log when it boots and turns the links off; it never stops the application or its workers, which boot the same service provider.

Jobs processed

The Workload page also charts how many jobs completed and failed per time bucket, like Horizon’s throughput view. It reads the counters the broker already keeps for every queue, through GET /api/v1/analytics/queue-ops, so it adds no write to the job path and needs no setting.

The 2.0 broker counts the legs of a transaction too. A release acknowledges the job as completed and pushes its copy in one transaction, so each released attempt adds one to Completed and one to Dispatched, and a hand-back does the same for each job it returns. A delayed job is never counted as dispatched, because a timer’s fire is not a push. An acknowledgement is counted as it was asked for, before the broker judges it, so a refused one counts too. The counters are per queue: every consumer group that acknowledges the queue adds to them.

The 1h, 6h, 24h and 7d links set the window, and the window sets the bucket width the broker uses: 1 minute for an hour, 5 for six hours, 15 for a day and 60 for a week. The window stays in the address (?range=24h) and in the automatic refresh, and times are in UTC. A 2.0 broker keeps these per-queue counters for 24 hours by default, so the week view shows only the last day unless the operator raises QUEEN_DASH_QUEUE_RETENTION_H. In a cluster every node counts the requests it served and writes its counters once a minute, and the broker adds the nodes up when it answers, so the current minute appears once it has ended. A table under the chart gives the totals per queue. The page sends one request per queue, in parallel, with the read token when one is set and a timeout of at most five seconds, and caches the result for fifteen seconds. A queue whose counters cannot be read is marked unavailable without hiding the others.

Failed jobs and the broker’s dead-letter queue

Laravel stays the index of failed Laravel jobs, and its commands keep the broker’s dead-letter entry in step with the failed_jobs row (failed jobs):

php artisan queue:failed
php artisan queue:retry <id>
php artisan queue:forget <id>
php artisan queue:prune-failed

The failed-jobs page shows dashboard.failed_jobs_limit jobs (50 by default), newest first, with Older and Newest links. It pages with a keyset cursor instead of an offset: on a database store each page is one range read on the primary key, with one extra row to learn whether an older page exists, and never a COUNT(*). A table with millions of failed jobs costs the same per page as a table with ten, and the total shows as a lower bound (51+) when there are more. A file store is read whole, within the 4 MiB bound the panel always applies, and its pages are positions, so a new failure while you read an older page shifts it by one row.

Why a job failed

Each row opens its job in a drawer beside the list; Open as page shows the same detail at /queen/failed-jobs/{id}, which is also where the row leads without JavaScript. Automatic refresh pauses while the drawer is open. The detail shows the job class, the queue and connection, the maximum tries and timeout read from the payload, the exception class and message under Why it failed, the stack trace, and the queue:retry command for that job. The message, the trace and the command each have a Copy button. The payload is never displayed, paths under the application root are shown relative to it, and the exception and payload are read from the store cut to 1 MiB, in SQL on a database store, so a row of many megabytes costs no more memory than that. The page shows no attempt count, because Laravel keeps its payload counter current only on the Redis driver and it would read 0 for a job that used every try. The exception message can carry application data, which is why the page sits behind the same Gate as the rest.

Retry now (PHP client 1.9.0) runs Laravel’s queue:retry for that one job, as the command does, so the job keeps its retry fence and its dead-letter entry is cleared with the row. It posts to /queen/failed-jobs/{id}/retry with the CSRF token and the same authorization as the rest of the panel. A job that goes back onto its queue leaves the list; a retry that cannot run keeps the job and shows Laravel’s reason. Forgetting, flushing and pruning have no button: use the commands.

Do not retry a Laravel job from the dead-letter page of the Queen dashboard: that replay knows nothing about failed_jobs, the attempt count or the cleanup. The two dashboards cover different ground on purpose:

Tuning advice and settings

Since PHP client 1.9.0 the Configuration page opens with Tuning advice, read from this application’s settings, what the running supervisor published, the failed-job count and the last hour of job metrics. Each item has a severity, the evidence, what to do, and a link to these pages. When nothing calls for a change, it says so.

The pools and shutdown_grace are the running supervisor’s when one published its status, otherwise this application’s. The critical items always read this application’s pools: the supervisor will not start such a pool, so only a worker started another way runs it. The longest run of a class comes from the job metrics’ max_ms, which earlier workers did not record, so a class recorded only by earlier workers gets no deploy advice.

Below the advice, Settings lists every Queen setting as this host resolves it, with its value, default and meaning, and the environment variable of the settings that read one: the connection, the supervisor (including lease_service) and the pools. The pools are the ones the running supervisor published, or this application’s when none did. The supervisor does not publish backoff, max jobs, max time and sleep, so those come from this application’s pool of the same name. A supervisor started with other environment variables, such as a worker pod, runs with its own values; php artisan queen:supervisor-config on its host checks its whole supervisor configuration.

A changed value is in bold, a value of the wrong type or out of range shows as invalid, and a value the connection refuses with another setting, such as prefetch above 1 without lease_renewal, shows the reason, as does a pool with min_processes above max_processes. A setting whose name contains token, secret, password or key shows only set or not set, a broker URL only its scheme, host and port, and the headers only how many there are.

A supervisor on another host

The panel reads one local state directory. When the dashboard is served by other processes than the supervisor (web pods beside a worker pod, say), that directory is empty and the supervisor shows as unavailable. Either engine can close the gap by also publishing its status to the broker’s key/value store:

QUEEN_SUPERVISOR_REMOTE_STATUS=true

Set it on every supervisor host and on every web host. The publishers and the reader must use the same key, one per application and environment that share a broker. The key defaults to a slug of APP_NAME and APP_ENV, such as orders-production, so hosts that share both values agree on it. Set supervisor.remote_status.key in config/queen.php when they do not, or when two applications that keep Laravel’s default APP_NAME share a broker. Each supervisor instance publishes into its own slot under the key, named by its instance_id, so several hosts or pods never overwrite each other.

The key is a group name: 1–255 ASCII letters, digits, dots, underscores or hyphens, starting with a letter or digit. Names are case-sensitive and cannot contain slashes; coordination is reserved. See the publication contract for identity, compatibility and requirements for other implementations. The broker dashboard’s Supervisors page can also read these publications, grouped across applications, without a Laravel web host.

The Laravel Supervisors page then shows one card per instance: a live local supervisor first, then every published one, live before stale, each with its host, PID and last heartbeat. The overview, the header and the notices add up workers, draining processes and the process budget over the live instances, and report ready or healthy only when every live instance is. A stopping or stopped master is not live, so the old pod of a rollout stays listed as stale until its copy expires and never counts in those totals. A published instance is read-only: pause, continue and terminate stay with php artisan queen:supervisor on its own host, and a control request for it answers 409. Liveness comes from the published heartbeat alone, because a web host cannot check another host’s lock, so keep heartbeat_timeout and the supervisors’ clocks sane: a copy older than the heartbeat timeout shows as stale, and an expired one disappears.

The document travels split across <key>/<instance_id>/head and <key>/<instance_id>/chunk/NNNN, written in one key/value batch, so its size never runs into the store’s value ceiling (64 KiB by default, QUEEN_KV_MAX_VALUE_BYTES). The panel lists every slot with getPrefix and decodes each from one page, which is one snapshot; a slot a page cuts through is read whole on the next one. Chunks left by an earlier, larger write are recognized by their write id and expire with their TTL. A document at <key>/head, the single slot of releases before per-instance slots, is still read, so web hosts can be upgraded before their supervisors.

Publishing is a key/value write, so it uses the connection’s write credential, never read_bearer_token. It is best effort: one request timeout per broker endpoint is added to the heartbeat budget, a failure is reported once per failure streak, and a broker outage shows the supervisor as stale without ever stopping supervision. The Rust engine publishes from PHP client 1.5.0 (supervisor 0.2.0), and into its own instance slot from 1.6.0 (supervisor 0.3.0): queen:supervisor-config --for-engine hands it the setting with the connection’s write credential, and it publishes after every status write, at most once per interval except on a state change, which publishes at once, as the PHP engine does.

Behind a load balancer

Without remote status the panel is not a multi-host view. Route the administration path to the host that owns the supervisor, or use a sticky admin endpoint: a page read from host A followed by a control posted to host B fails the instance fence on purpose.

The panel loads no fonts or assets from a CDN and has no inline scripts, style blocks or style attributes. The package serves its content-hashed stylesheet and refresh script from the dashboard routes, with Subresource Integrity, and its Content Security Policy allows scripts, styles and fetch only from the same origin. Dynamic responses are no-store; successful asset responses are cached privately for a year, immutable, with transformations disabled so the integrity digest holds, and error responses are never cached. Responses also deny framing and MIME sniffing and send no referrer.

Some web servers answer every *.css and *.js request from the public directory and never reach PHP (a common nginx or Caddy rule for static files). The asset routes then return the web server’s 404, and the panel renders unstyled with whole-page refreshes. Publish the assets, as Horizon does with its own:

php artisan vendor:publish --tag=queen-assets --force

The copies land in public/vendor/queen/dashboard.css and public/vendor/queen/dashboard.js. The panel links to each, with the same integrity digest, only while it is byte-identical to the packaged file, so a stale copy after an upgrade falls back to the route and can never serve the wrong styles. The files are also tagged laravel-assets, which Laravel’s default post-update-cmd republishes on every composer update; in a container build, run the publish command beside your other asset steps.

For Prometheus and autoscalers, the same state is on /queen/metrics, with its own bearer token and no session (monitoring).