Kinetis Vector 0.14: A Queue Dashboard in the Admin#
Two days ago kinetis/queue-failed-jobs started keeping the jobs your
worker gives up on, with commands to list, retry, forget and prune
them. kinetis/vector 0.14.0 and @kinetis/vector-ui 0.12.0 put the
same work in the admin: a Queues page that shows how many jobs are
waiting, which ones failed and why, and how your jobs have run over the
last minutes or days.
Nothing to install#
The dashboard is part of Vector. Once you upgrade, Queues shows up
in the menu beside Jobs whenever the application has a queue
configured, which kinetis/queue does when QUEUE_CONNECTION is set.
Tell it which queues to watch, in the order you want them listed:
VECTOR_QUEUES=default,mail,reports
A worker’s --queue list is a command-line argument that no HTTP
process can see, so when VECTOR_QUEUES is unset the dashboard watches
default only.
For failed jobs, install kinetis/queue-failed-jobs 1.1 or later.
Vector only suggests the package. Without it the page has no failed
jobs, and the rest of the dashboard works as usual.
Three tabs#
Overview shows each watched queue’s waiting jobs and failed count, refreshed every five seconds while the page is open. Clear empties a queue, after you type its name to confirm.
Failed jobs lists the failed jobs, with filters by queue, job class and time. Open a job to see its exception and arguments. Retry one job or a selection of up to 50, forget one, or prune everything older than a number of days.
Metrics counts every attempt the worker settles, per minute, queue and job class: succeeded, released and failed, with average and longest durations. Pick a window from 15 minutes to 7 days and you get totals, a sparkline of attempts per minute, and a table per queue and per job class.
There is also a dashboard card, QueuesWidget, with the waiting and
failed counts and a link to the page. Add it to one of your dashboards’
widgets().
Read-only until you say otherwise#
By default anyone Vector admits can look, and nobody can retry, forget,
prune or clear. To let some users change things, bind your own
QueueDashboardPolicyInterface in bootstrap.php. It decides view,
retry, forget and prune, and clear per queue, so you can let
admins empty a scratch queue but not mail. The page offers only the
actions the policy allows, and every endpoint asks the policy again.
Every retry, forget, prune and clear is written to Vector’s audit trail.
#[Sensitive] job arguments show as [redacted]. Exception messages
are shown exactly as the job threw them, to anyone who can view the
dashboard, so keep secrets out of them.
Metrics need a table#
The metrics live in vector_queue_metrics, one of Vector’s own tables.
After upgrading, publish its migration and run it:
vendor/bin/kinetis vector:install
vendor/bin/kinetis migrate
On MySQL it needs 8.0.19 or later. Until the table exists, each worker
logs one warning a minute and your jobs run as before. Recording never
affects a job. Nothing prunes the table on its own, so run
vector:queues:prune-metrics --days=7 from your scheduler once a day.
To turn the metrics off, set VECTOR_QUEUE_METRICS=off.
The queue dashboard guide covers the policy, the endpoints and the metrics in detail.
Upgrading#
Upgrade kinetis/vector to 0.14.0 and @kinetis/vector-ui to 0.12.0
together:
The descriptor is version 5. The new UI refuses version 4, so upgrade both at once, and rebuild a hosted admin bundle.
vector:install-uiinstalls 0.12.0 by default.Node 26 is required for
@kinetis/vector-ui. Node 22 and 24 are no longer supported.kinetis/vectorrequireskinetis/framework1.24.3 andkinetis/queue1.9.1, and the other Kinetis patch releases built with Psalm 7.
The release also lets an application declare its own dashboard widget
types and render them with defineWidget, and lets definePage take
functions for title and group, so custom menu labels follow a change
of language. In the rich-text and Markdown editors, text typed right
after pressing a toolbar button no longer lands on the button.