Configuration

Database Configuration

Configure which database connection to use for monitoring data:

'database' => [
    'connection' => env('QUEUE_MONITOR_DB_CONNECTION'),
    'table_prefix' => 'queue_monitor_',
],

This allows you to store monitoring data separately from your application data if desired.

Dashboard analytics generate database-specific SQL for timestamp bucketing and queue pickup latency. The package supports MySQL/MariaDB, PostgreSQL, SQL Server, and SQLite for those expressions.

Payload Storage

Control how job payloads are stored for replay functionality:

'storage' => [
    // Store complete job payload for replay capability.
    // Defaults to enabled in local only; set QUEUE_MONITOR_STORE_PAYLOAD explicitly to override.
    'store_payload' => env('QUEUE_MONITOR_STORE_PAYLOAD', env('APP_ENV') === 'local'),

    // Maximum payload size in bytes (default: 64KB)
    'payload_max_size' => 65535,
],

Important: Payload storage is required for job replay. By default it is enabled in local and disabled outside local unless QUEUE_MONITOR_STORE_PAYLOAD is explicitly set. If disabled, replay functionality will not work.

Data Retention

Configure automatic cleanup of old job records:

'retention' => [
    // Number of days to retain job records
    'days' => 30,

    // Which statuses to prune (empty array = prune all statuses)
    'prune_statuses' => ['completed'],
],

Run pruning manually or via scheduled task:

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('queue-monitor:prune')->daily();

Worker Detection

Customize how workers and servers are identified:

'worker_detection' => [
    // Custom callable for determining server name
    // If null, uses gethostname()
    'server_name_callable' => null,

    // Enable Horizon detection
    'horizon_detection' => true,
],

Example custom server name:

'server_name_callable' => function() {
    return config('app.server_name', gethostname());
},

REST API

Configure the REST API for external integrations:

'api' => [
    'enabled' => env('QUEUE_MONITOR_API_ENABLED', env('APP_ENV') === 'local'),
    'prefix' => 'api/queue-monitor',
    'middleware' => ['api'],
    'rate_limit' => '60,1', // 60 requests per minute
],

The API defaults to enabled only in local. Set QUEUE_MONITOR_API_ENABLED=true explicitly in staging or production after adding authentication middleware and an authorization callback.

You can add custom middleware for authentication:

'middleware' => ['api', 'auth:sanctum'],

Dashboard Assets

Control how the built-in dashboard loads CSS and JavaScript:

'ui' => [
    'assets' => [
        // inline, public, or none
        'mode' => env('QUEUE_MONITOR_ASSET_MODE', 'inline'),
        'url' => env('QUEUE_MONITOR_ASSET_URL'),
    ],
],

Use inline for zero setup, public after publishing queue-monitor-assets, and none when a published/custom dashboard view loads assets from your application's own build. See Dashboard Assets for the full override workflow.

Health Checks

Tune health thresholds for your workload:

'health' => [
    'stuck_job_minutes' => env('QUEUE_MONITOR_HEALTH_STUCK_JOB_MINUTES', 30),
    'error_rate_threshold' => env('QUEUE_MONITOR_HEALTH_ERROR_RATE_THRESHOLD', 10.0),
    'queued_jobs_threshold' => env('QUEUE_MONITOR_HEALTH_QUEUED_JOBS_THRESHOLD', 1000),
    'processing_jobs_threshold' => env('QUEUE_MONITOR_HEALTH_PROCESSING_JOBS_THRESHOLD', 100),
    'storage_max_mb' => env('QUEUE_MONITOR_HEALTH_STORAGE_MAX_MB', 1000),
],

Use the readiness mode before launch:

php artisan queue-monitor:health --readiness
php artisan queue-monitor:health --readiness --json

Readiness checks validate production-sensitive configuration such as access control, API middleware, payload storage, retention limits, and Horizon timeout alignment.

Metrics Storage

Queue Monitor depends on laravel-queue-metrics for per-job CPU and memory instrumentation. Queue-metrics also provides aggregate persistence (worker heartbeats, throughput, baselines), but Queue Monitor doesn't need it.

Disable persistence (simplest setup)

If you only use Queue Monitor, disable metrics persistence to skip any storage backend:

QUEUE_METRICS_PERSISTENCE=false

Per-job CPU/memory still works. Only aggregate persistence is skipped.

Note: cboxdk/laravel-queue-autoscale requires persistence enabled. It reads worker heartbeats, throughput, and baselines from queue-metrics to make scaling decisions.

With persistence enabled (default)

When persistence is on, configure a storage backend in config/queue-metrics.php:

'persistence' => [
    'enabled' => env('QUEUE_METRICS_PERSISTENCE', true),
],

'storage' => [
    'driver' => env('QUEUE_METRICS_STORAGE', 'redis'),
    'connection' => env('QUEUE_METRICS_CONNECTION', 'default'),
    'prefix' => 'queue_metrics',
    // Recommended: 1000 for Redis, 500 for database driver
    'max_samples_per_key' => env('QUEUE_METRICS_MAX_SAMPLES', 1000),
],

Redis is the recommended driver. Database is available for low-scale workloads (< 10 workers) without Redis. See the installation guide for setup.

For full metrics configuration options, see the laravel-queue-metrics documentation.

Repository Bindings

Override default repository implementations:

'repositories' => [
    JobMonitorRepositoryContract::class => CustomJobMonitorRepository::class,
    TagRepositoryContract::class => CustomTagRepository::class,
    StatisticsRepositoryContract::class => CustomStatisticsRepository::class,
],

Action Bindings

Override default action implementations:

'actions' => [
    'record_job_queued' => CustomRecordJobQueuedAction::class,
    'replay_job' => CustomReplayJobAction::class,
    // ... more actions
],