PHPackages                             cboxdk/laravel-queue-autoscale - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Queues & Workers](/categories/queues)
4. /
5. cboxdk/laravel-queue-autoscale

ActiveLibrary[Queues & Workers](/categories/queues)

cboxdk/laravel-queue-autoscale
==============================

Intelligent, predictive autoscaling for Laravel queues with SLA/SLO-based optimization

v2.1.0(1mo ago)5248[2 PRs](https://github.com/cboxdk/laravel-queue-autoscale/pulls)MITPHPPHP ^8.3|^8.4|^8.5CI passing

Since Jan 21Pushed 1mo agoCompare

[ Source](https://github.com/cboxdk/laravel-queue-autoscale)[ Packagist](https://packagist.org/packages/cboxdk/laravel-queue-autoscale)[ Docs](https://github.com/cboxdk/laravel-queue-autoscale)[ GitHub Sponsors](https://github.com/cboxdk)[ RSS](/packages/cboxdk-laravel-queue-autoscale/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (28)Versions (8)Used By (0)

Laravel Queue Autoscale
=======================

[](#laravel-queue-autoscale)

[![Latest Version on Packagist](https://camo.githubusercontent.com/b4f4610ff91098436d03284bd905bf8798d0de6bfe4362dc25e95bf21cce555a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f63626f78646b2f6c61726176656c2d71756575652d6175746f7363616c652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/cboxdk/laravel-queue-autoscale)[![GitHub Tests Action Status](https://camo.githubusercontent.com/74c9b2d1786facfd3a6f37d6a392412ea909e9af791a353420fdbeccb525c769/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f63626f78646b2f6c61726176656c2d71756575652d6175746f7363616c652f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/cboxdk/laravel-queue-autoscale/actions?query=workflow%3Atests+branch%3Amain)[![GitHub Code Quality Action Status](https://camo.githubusercontent.com/f7cfa416c304c3a2f24503340c7d3c2b0dc38388e2315c1f0fdb6e292ca0787c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f63626f78646b2f6c61726176656c2d71756575652d6175746f7363616c652f636f64652d7175616c6974792e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307175616c697479267374796c653d666c61742d737175617265)](https://github.com/cboxdk/laravel-queue-autoscale/actions?query=workflow%3Acode-quality+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/8b98c90fd24c0b8e87f5c3cfbe20dda86a7a61e908bf22c3e987207ca4985eba/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f63626f78646b2f6c61726176656c2d71756575652d6175746f7363616c652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/cboxdk/laravel-queue-autoscale)

**Intelligent, predictive autoscaling for Laravel queues with SLA/SLO-based optimization.**

Laravel Queue Autoscale is a smart queue worker manager that automatically scales your queue workers based on workload, predicted demand, and service level objectives. Unlike traditional reactive solutions, it uses a **hybrid predictive algorithm** combining queueing theory (Little's Law), trend analysis, and backlog-based scaling to maintain your SLA targets.

Features
--------

[](#features)

- 🎯 **SLA/SLO-Based Scaling** - Define max pickup time instead of arbitrary worker counts
- 📈 **Predictive Algorithm** - Proactive scaling using trend analysis and forecasting
- 🔬 **Queueing Theory Foundation** - Little's Law (L = λW) for steady-state calculations
- ⚡ **SLA Breach Prevention** - Aggressive backlog drain when approaching SLA violations
- 🖥️ **Resource-Aware** - Respects CPU and memory limits from system metrics
- 🔄 **Metrics-Driven** - Uses [`laravel-queue-metrics`](https://github.com/cboxdk/laravel-queue-metrics) for queue discovery and all metrics
- 🎛️ **Extensible** - Custom scaling strategies and policies via interfaces
- 📊 **Event Broadcasting** - React to scaling decisions, SLA predictions, worker changes
- 🛡️ **Graceful Shutdown** - SIGTERM → SIGKILL worker termination
- 🚀 **High Performance** - Drift-corrected evaluation loop and efficient process management
- 🔒 **Secure by Design** - Safe process spawning and resource isolation
- 💎 **DX First** - Clean API following Spatie package conventions

Requirements
------------

[](#requirements)

- PHP 8.3+
- Laravel 11.0+
- [`cboxdk/laravel-queue-metrics`](https://github.com/cboxdk/laravel-queue-metrics) ^1.0.0
- [`cboxdk/system-metrics`](https://github.com/cboxdk/system-metrics) ^1.2

Installation
------------

[](#installation)

Install via Composer:

```
composer require cboxdk/laravel-queue-autoscale
```

Publish the configuration file:

```
php artisan vendor:publish --tag=queue-autoscale-config
```

### Setup Metrics Package

[](#setup-metrics-package)

The autoscaler requires [`laravel-queue-metrics`](https://github.com/cboxdk/laravel-queue-metrics) for queue discovery and metrics collection:

```
# Install metrics package (if not auto-installed via dependency)
composer require cboxdk/laravel-queue-metrics

# Publish metrics configuration
php artisan vendor:publish --tag=queue-metrics-config
```

Configure storage backend in `.env`:

```
# Option A: Redis (recommended - fast, in-memory)
QUEUE_METRICS_STORAGE=redis
QUEUE_METRICS_CONNECTION=default

# Option B: Database (persistent storage)
QUEUE_METRICS_STORAGE=database
```

If using database storage, publish and run migrations:

```
php artisan vendor:publish --tag=laravel-queue-metrics-migrations
php artisan migrate
```

**📚 See [Metrics Package Documentation](https://github.com/cboxdk/laravel-queue-metrics) for advanced configuration.**

Quick Start
-----------

[](#quick-start)

### 1. Configure SLA Targets (Optional)

[](#1-configure-sla-targets-optional)

**Zero Config:** By default, the package uses the "Balanced" profile (30s SLA). You can skip configuration if this suits you.

To customize, edit `config/queue-autoscale.php`:

```
return [
    'enabled' => true,

    // Choose a preset profile: 'balanced', 'critical', 'high_volume', 'bursty', 'background'
    'sla_defaults' => \Cbox\LaravelQueueAutoscale\Configuration\ProfilePresets::balanced(),

    // ... or customize manually
    'queues' => [
        'critical' => [
            'max_pickup_time_seconds' => 5,   // Strict SLA
            'max_workers' => 20,
        ],
    ],
];
```

### 2. Run the Autoscaler

[](#2-run-the-autoscaler)

```
php artisan queue:autoscale
```

The autoscaler will:

- Receive all queues and metrics from [`laravel-queue-metrics`](https://github.com/cboxdk/laravel-queue-metrics)
- Apply scaling algorithms to meet SLA targets
- Scale workers up/down based on calculations
- Respect CPU/memory limits from [`system-metrics`](https://github.com/cboxdk/system-metrics)
- Log all scaling decisions

### 3. Monitor with Events

[](#3-monitor-with-events)

```
use Cbox\LaravelQueueAutoscale\Events\WorkersScaled;
use Cbox\LaravelQueueAutoscale\Events\SlaBreachPredicted;

Event::listen(WorkersScaled::class, function (WorkersScaled $event) {
    Log::info("Scaled {$event->queue}: {$event->from} → {$event->to} workers");
    Log::info("Reason: {$event->reason}");
});

Event::listen(SlaBreachPredicted::class, function (SlaBreachPredicted $event) {
    // Alert when SLA breach is predicted
    Notification::route('slack', env('SLACK_ALERT_WEBHOOK'))
        ->notify(new SlaBreachAlert($event->decision));
});
```

How It Works
------------

[](#how-it-works)

### Hybrid Predictive Algorithm

[](#hybrid-predictive-algorithm)

The autoscaler uses three complementary approaches and takes the **maximum** (most conservative):

#### 1. **Rate-Based (Little's Law)**

[](#1-rate-based-littles-law)

```
Workers = Arrival Rate × Avg Processing Time

```

Calculates steady-state workers needed for current load.

#### 2. **Trend-Based (Predictive)**

[](#2-trend-based-predictive)

```
Workers = Predicted Rate × Avg Processing Time

```

Uses trend analysis to predict future arrival rates and scale proactively.

#### 3. **Backlog-Based (SLA Protection)**

[](#3-backlog-based-sla-protection)

```
Workers = Backlog / (Time Until SLA Breach / Avg Job Time)

```

Aggressively scales when approaching SLA violations.

### Resource Constraints

[](#resource-constraints)

All calculations are bounded by:

- **System capacity** - CPU/memory limits from `system-metrics`
- **Config bounds** - min/max workers from configuration
- **Cooldown periods** - Prevents scaling thrash

See [Architecture Documentation](docs/algorithms/architecture.md) for detailed algorithm explanation.

Configuration Reference
-----------------------

[](#configuration-reference)

### SLA Defaults

[](#sla-defaults)

```
'sla_defaults' => [
    // Maximum time a job should wait before being picked up (seconds)
    'max_pickup_time_seconds' => 30,

    // Minimum workers to maintain (even if queue is empty)
    'min_workers' => 1,

    // Maximum workers allowed for this queue
    'max_workers' => 10,

    // Cooldown period between scaling operations (seconds)
    'scale_cooldown_seconds' => 60,
],
```

### Per-Queue Overrides

[](#per-queue-overrides)

```
'queues' => [
    'queue-name' => [
        'max_pickup_time_seconds' => 60,
        'min_workers' => 2,
        'max_workers' => 20,
        'scale_cooldown_seconds' => 30,
    ],
],
```

### Prediction Settings

[](#prediction-settings)

```
'prediction' => [
    // How far ahead to forecast (seconds)
    'forecast_horizon_seconds' => 60,

    // When to trigger backlog drain (0-1, e.g., 0.8 = 80% of SLA time)
    'breach_threshold' => 0.8,
],
```

### Resource Limits

[](#resource-limits)

```
'resource_limits' => [
    // Maximum CPU usage percentage
    'max_cpu_percent' => 90,

    // Number of CPU cores to reserve
    'reserve_cpu_cores' => 0.5,

    // Maximum memory usage percentage
    'max_memory_percent' => 85,

    // Estimated memory per worker (MB)
    'worker_memory_mb_estimate' => 128,
],
```

### Worker Settings

[](#worker-settings)

```
'worker' => [
    // Worker process arguments
    'tries' => 3,
    'timeout_seconds' => 3600,
    'sleep_seconds' => 3,

    // Graceful shutdown timeout before SIGKILL
    'shutdown_timeout_seconds' => 30,
],
```

### Strategy Configuration

[](#strategy-configuration)

```
'strategy' => [
    // Scaling strategy class (must implement ScalingStrategyContract)
    'class' => \Cbox\LaravelQueueAutoscale\Scaling\Strategies\PredictiveStrategy::class,
],
```

Custom Scaling Strategies
-------------------------

[](#custom-scaling-strategies)

Implement your own scaling logic:

```
use Cbox\LaravelQueueAutoscale\Contracts\ScalingStrategyContract;
use Cbox\LaravelQueueAutoscale\Configuration\QueueConfiguration;

class CustomStrategy implements ScalingStrategyContract
{
    public function calculateTargetWorkers(object $metrics, QueueConfiguration $config): int
    {
        // Your custom logic here
        return (int) ceil($metrics->processingRate * 2);
    }

    public function getLastReason(): string
    {
        return 'Custom strategy: doubled the processing rate';
    }

    public function getLastPrediction(): ?float
    {
        return null; // Optional: estimated pickup time
    }
}
```

Register in config:

```
'strategy' => [
    'class' => \App\Scaling\CustomStrategy::class,
],
```

Scaling Policies
----------------

[](#scaling-policies)

Add before/after hooks to scaling operations:

```
use Cbox\LaravelQueueAutoscale\Contracts\ScalingPolicy;
use Cbox\LaravelQueueAutoscale\Scaling\ScalingDecision;

class NotifySlackPolicy implements ScalingPolicy
{
    public function beforeScaling(ScalingDecision $decision): void
    {
        if ($decision->shouldScaleUp()) {
            Slack::notify("About to scale up {$decision->queue}");
        }
    }

    public function afterScaling(ScalingDecision $decision, bool $success): void
    {
        if (!$success) {
            Slack::notify("Failed to scale {$decision->queue}");
        }
    }
}
```

Register in config:

```
'policies' => [
    \App\Policies\NotifySlackPolicy::class,
],
```

Events
------

[](#events)

Subscribe to scaling events:

### ScalingDecisionMade

[](#scalingdecisionmade)

```
use Cbox\LaravelQueueAutoscale\Events\ScalingDecisionMade;

Event::listen(ScalingDecisionMade::class, function (ScalingDecisionMade $event) {
    $decision = $event->decision;

    Log::info('Scaling decision', [
        'queue' => $decision->queue,
        'current' => $decision->currentWorkers,
        'target' => $decision->targetWorkers,
        'reason' => $decision->reason,
    ]);
});
```

### WorkersScaled

[](#workersscaled)

```
use Cbox\LaravelQueueAutoscale\Events\WorkersScaled;

Event::listen(WorkersScaled::class, function (WorkersScaled $event) {
    Metrics::gauge('queue.workers', $event->to, [
        'queue' => $event->queue,
        'action' => $event->action, // 'scaled_up' or 'scaled_down'
    ]);
});
```

### SlaBreachPredicted

[](#slabreachpredicted)

```
use Cbox\LaravelQueueAutoscale\Events\SlaBreachPredicted;

Event::listen(SlaBreachPredicted::class, function (SlaBreachPredicted $event) {
    $decision = $event->decision;

    // Alert when pickup time is predicted to exceed SLA
    if ($decision->isSlaBreachRisk()) {
        PagerDuty::alert("SLA breach predicted for {$decision->queue}");
    }
});
```

Advanced Usage
--------------

[](#advanced-usage)

### Running as Daemon

[](#running-as-daemon)

Use Supervisor to keep the autoscaler running:

```
[program:queue-autoscale]
command=php /path/to/artisan queue:autoscale
directory=/path/to/project
user=www-data
autostart=true
autorestart=true
redirect_stderr=true
stdout_logfile=/path/to/logs/autoscale.log
```

### Custom Evaluation Interval

[](#custom-evaluation-interval)

```
php artisan queue:autoscale --interval=10
```

Default is 5 seconds between evaluations.

### Debugging

[](#debugging)

Enable detailed logging:

```
'log_channel' => 'stack', // Use your preferred channel
```

View scaling decisions:

```
tail -f storage/logs/laravel.log | grep autoscale
```

Metrics Integration
-------------------

[](#metrics-integration)

**This package does NOT discover queues or collect metrics itself.** All queue discovery and metrics collection is delegated to [`laravel-queue-metrics`](https://github.com/cboxdk/laravel-queue-metrics):

```
use Cbox\LaravelQueueMetrics\QueueMetrics;

// The ONLY source of queue data for autoscaling
$allQueues = QueueMetrics::getAllQueuesWithMetrics();

foreach ($allQueues as $queue) {
    echo "Queue: {$queue->connection}/{$queue->queue}\n";
    echo "Processing Rate: {$queue->processingRate} jobs/sec\n";
    echo "Backlog: {$queue->depth->pending} jobs\n";
    echo "Oldest Job: {$queue->depth->oldestJobAgeSeconds}s\n";
    echo "Trend: {$queue->trend->direction}\n";
}
```

**Package Responsibilities:**

### [laravel-queue-metrics](https://github.com/cboxdk/laravel-queue-metrics) (dependency)

[](#laravel-queue-metrics-dependency)

- ✅ Scans all configured queue connections
- ✅ Discovers active queues
- ✅ Collects queue depth and age metrics
- ✅ Calculates processing rates
- ✅ Analyzes trends and forecasts

### laravel-queue-autoscale (this package)

[](#laravel-queue-autoscale-this-package)

- ✅ Applies scaling algorithms (Little's Law, Trend Prediction, Backlog Drain)
- ✅ Makes SLA-based scaling decisions
- ✅ Manages worker pool lifecycle (spawn/terminate)
- ✅ Enforces resource constraints (CPU/memory limits)
- ✅ Executes scaling policies and broadcasts events

Comparison with Horizon
-----------------------

[](#comparison-with-horizon)

FeatureLaravel HorizonQueue Autoscale**Scaling Logic**Manual supervisor configAutomatic predictive**Optimization Goal**Worker count targetsSLA/SLO targets**Algorithm**Static configurationHybrid (Little's Law + Trend + Backlog)**Resource Awareness**NoYes (CPU/memory limits)**Queue Discovery**Manual queue configVia metrics package**Prediction**Reactive onlyProactive trend-based**SLA Protection**NoYes (breach prevention)**Extensibility**LimitedFull (strategies, policies)Testing
-------

[](#testing)

Run the test suite:

```
composer test
```

Run with coverage:

```
composer test:coverage
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for recent changes.

Contributing
------------

[](#contributing)

Please see [Contributing Guide](docs/advanced-usage/contributing.md) for details.

Security
--------

[](#security)

If you discover any security related issues, please email  instead of using the issue tracker.

Credits
-------

[](#credits)

- [Sylvester Damgaard](https://github.com/sylvesterdamgaard)
- [All Contributors](../../contributors)

Resources
---------

[](#resources)

### Documentation

[](#documentation)

- **[Architecture](docs/algorithms/architecture.md)** - Deep dive into the hybrid predictive algorithm, queueing theory, and system design
- **[Troubleshooting](docs/basic-usage/troubleshooting.md)** - Common issues, debugging tips, and solutions
- **[examples/README.md](examples/README.md)** - Practical examples and templates for custom strategies and policies

### Examples

[](#examples)

- **Custom Strategies**

    - [TimeBasedStrategy](examples/Strategies/TimeBasedStrategy.php) - Scale workers based on time-of-day patterns
    - [CostOptimizedStrategy](examples/Strategies/CostOptimizedStrategy.php) - Prioritize cost efficiency with conservative scaling
- **Custom Policies**

    - [SlackNotificationPolicy](examples/Policies/SlackNotificationPolicy.php) - Send Slack alerts on scaling events
    - [MetricsLoggingPolicy](examples/Policies/MetricsLoggingPolicy.php) - Log detailed metrics to dedicated file
- **Configuration Patterns**

    - [config-examples.php](examples/config-examples.php) - 8 real-world configuration examples for different use cases

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

48

—

FairBetter than 94% of packages

Maintenance93

Actively maintained with recent releases

Popularity21

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 93.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~24 days

Total

4

Last Release

35d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/b9761a79e61f2d5b9d650510dfb3555da18daf38f027aa84012c937e397e39a7?d=identicon)[cboxdk](/maintainers/cboxdk)

---

Top Contributors

[![sylvesterdamgaard](https://avatars.githubusercontent.com/u/2431914?v=4)](https://github.com/sylvesterdamgaard "sylvesterdamgaard (75 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (4 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)")

---

Tags

laravelqueueworkerslaslocboxautoscalingpredictiveautoscalelittles-law

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/cboxdk-laravel-queue-autoscale/health.svg)

```
[![Health](https://phpackages.com/badges/cboxdk-laravel-queue-autoscale/health.svg)](https://phpackages.com/packages/cboxdk-laravel-queue-autoscale)
```

###  Alternatives

[croustibat/filament-jobs-monitor

Background Jobs monitoring like Horizon for all drivers for FilamentPHP

254255.2k6](/packages/croustibat-filament-jobs-monitor)[harris21/laravel-fuse

Circuit breaker for Laravel queue jobs. Protect your workers from cascading failures.

3786.5k](/packages/harris21-laravel-fuse)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)