Queue Operations

Queue Operations is the Capell Diagnostics wrapper around croustibat/filament-jobs-monitor. Capell keeps the upstream package as the low-level telemetry collector and owns the admin page, queries, actions, permissions, retention defaults, and screenshots.

Use this page when you are changing queue monitoring, failed-job retry flows, pending database queue cleanup, or the Diagnostics queue screenshots.

Upstream Credit

The queue history table is powered by croustibat/filament-jobs-monitor, maintained at ultraviolettes/filament-jobs-monitor. That package listens to Laravel queue events and writes queue_monitors rows. Diagnostics does not fork that work; it wraps it with Capell-specific configuration and a safer admin surface.

Keep the upstream package credited in:

• ../README.md, under Built With and Screens And Workflow.
• credits-and-acknowledgements.md, under Open-source Packages And Authors.
• overview.md, under Queue Operations.
• screenshots.json, in Queue Operations capture notes.
• ../capell.json, in marketplace screenshot captions and package metadata.

Runtime Shape

• DiagnosticsServiceProvider binds Croustibat\FilamentJobsMonitor\Models\QueueMonitor to Capell\Diagnostics\Models\QueueMonitor.
• The upstream Filament navigation is disabled. Capell exposes QueueHealthPage as the Diagnostics-owned Queue Operations surface.
• The guarded migration creates an upstream-compatible queue_monitors table when the host app has not already published the upstream migration.
• config/capell-diagnostics.php controls retention days, monitored queues, Capell queue config paths, pending jobs, retry, deletion, and pruning.
• BuildQueueOperationsStatsAction aggregates totals, failures, running jobs, pending jobs, average runtime, and daily trends without the upstream widget’s repeated per-day count loop.
• Retry, bulk retry, pending deletion, and pruning are handled by typed Diagnostics Actions instead of Filament closures owning domain logic.

Admin Page

QueueHealthPage keeps the existing Capell navigation label capell-admin::navigation.queue_health and now renders:

• History tab from queue_monitors.
• Failed jobs tab from Laravel’s failed_jobs table.
• Pending jobs tab only when queue.default is database and the configured jobs table exists.
• Filters for status, queue, date range, and job class.
• Safer actions for retrying failed jobs, deleting pending database queue rows, and pruning old monitor rows.

Access is restricted to super admins and users that already have Diagnostics access or view permissions. This is an operations-only surface, not a client-admin feature.

Configuration

The Diagnostics config is the Capell source of truth:

'queue_monitor' => [
    'retention_days' => 14,
    'queues' => ['default'],
    'queue_config_paths' => [
        'capell-email-studio.queue',
        'capell-newsletter.sync.queue',
        'capell-public-actions.queue',
        'migration-assistant.queue.name',
    ],
    'pending_jobs_enabled' => true,
    'retry_enabled' => true,
    'delete_pending_enabled' => true,
    'prune_enabled' => true,
    'trend_days' => 7,
],

DiscoverQueueMonitorQueuesAction merges the explicit queue list, configured Capell package queue paths, and the active Laravel queue connection’s queue name. Keep that Action as the only queue discovery boundary so screenshots, stats, upstream config, and pending queries agree.

Screenshots

The screenshot contract lives in screenshots.json. Queue Operations screenshots should use dummy operational data so the page is useful in the Capell app and marketplace without exposing real job names, customer payloads, or exception details.

Generated dummy-data screenshots are stored under:

• packages/diagnostics/docs/assets/screenshots/queue-health-page.png
• packages/diagnostics/docs/assets/screenshots/queue-health-page-dark.png
• packages/diagnostics/docs/screenshots/queue-health-page.png
• packages/diagnostics/docs/screenshots/queue-health-page-dark.png
• packages/diagnostics/docs/screenshots/diagnostics-dashboard.png
• packages/diagnostics/docs/screenshots/system-health-page.png
• packages/diagnostics/docs/screenshots/permission-audit-page.png
• packages/diagnostics/docs/screenshots/command-palette-page.png
• packages/diagnostics/docs/screenshots/health-widgets-on-the-admin-dashboard.png

The local fixture source is assets/screenshots/diagnostics-dummy-screens.html. It is documentation-only. It exists to keep package docs and marketplace screenshots deterministic when a real host app does not have representative queue history.

Verification

Run the package test slice after queue operation changes:

vendor/bin/pest packages/diagnostics/tests --configuration=phpunit.xml

Useful focused tests:

• packages/diagnostics/tests/Feature/Actions/DashboardReports/QueueOperationsActionsTest.php
• packages/diagnostics/tests/Feature/Filament/Pages/QueueHealthPageTest.php

The Filament tests cover access, pending tab visibility, Unix timestamp filtering for database queue jobs, and failed-tab-only bulk retry visibility.