Vantage

A Laravel package that tracks and monitors your queue jobs. Automatically records job execution history, failures, retries, and provides a simple web interface to view everything.

Installation

composer require storviaio/vantage
php artisan vendor:publish --tag=vantage-config
php artisan migrate

The package will automatically register itself using

Publishing Assets:

• Config: php artisan vendor:publish --tag=vantage-config
• Views: php artisan vendor:publish --tag=vantage-views (optional, for customization)
• Migrations: Automatically loaded, but you can publish with php artisan vendor:publish --tag=vantage-migrations if needed

Requirements

• Laravel 10.x, 11.x, 12.x, or 13.x
• PHP 8.2, 8.3, or 8.4
• One of the following databases:
  • MySQL 5.7+ / MariaDB 10.3+
  • PostgreSQL 9.6+
  • SQLite 3.8.8+

Features

Universal Queue Driver Support

Works with all Laravel queue drivers - database, Redis, SQS, Beanstalkd, and any other driver. Unlike other monitoring tools that require specific drivers, Vantage tracks jobs from any queue driver and saves all data to your database for persistent tracking and analysis.

Job Tracking

Every job gets tracked in the vantage_jobs table with:

• Job class, queue, connection
• Status (processing, processed, failed)
• Start/finish times and duration
• UUID for tracking across retries
• All data saved to database - complete history of every job execution

Failure Details

When jobs fail, we store the exception class, message, and full stack trace. Much easier to debug than Laravel's default failed_jobs table.

Visit /vantage/failed to see all failed jobs with exception details and retry options.

Web Interface

Visit /vantage to access the comprehensive monitoring dashboard:

Dashboard (/vantage) - Overview of your queue system:

• Statistics Cards: Total jobs, processed, failed, processing, and success rate
• Queue Depth Monitoring: Real-time pending job counts per queue with health status
• Success Rate Trend Chart: Visual representation of job success/failure over time
• Top Failing Jobs: See which job classes fail most often
• Top Exceptions: Most common error types with counts
• Recent Jobs Table: Latest 20 jobs with quick actions
• Recent Batches: Track Laravel job batches with success/failure rates
• Time Period Filters: View data for last hour, 6 hours, 24 hours, 7 days, 30 days, or all time

Recent Jobs Table - Quick view of the latest 20 jobs with status, duration, and quick actions:

The Recent Jobs table appears on the dashboard showing:

• Job ID, class name, and queue
• Tags associated with each job
• Status indicators (Processing, Processed, Failed)
• Duration and creation time
• Quick "View" action to see full job details

Recent Batches - Track Laravel job batches with success/failure rates:

Jobs List - View and filter all jobs with advanced filtering options:

Visit /vantage/jobs to access the jobs list with powerful filtering capabilities:

• Filter by status (processed, failed, processing)
• Filter by queue name
• Filter by job class (partial match supported)
• Filter by tags (supports multiple tags with "all" or "any" mode)
• Filter by date range
• Popular tags cloud for quick filtering
• Pagination (50 jobs per page)

Filter jobs by status, queue, job class, tags, and date range:

Job Details (/vantage/jobs/{id}) - Comprehensive job information:

• Basic Information: Status, UUID, queue, connection, job class
• Timing: Start time, finish time, duration
• Exception Details: Full exception class, message, and stack trace for failed jobs
• Payload: Complete job payload with JSON formatting
• Tags: All tags associated with the job
• Retry Chain: View original job and all retry attempts
• Quick Actions: Retry failed jobs directly from the details page

Note: The dashboard requires authentication by default. Make sure you're logged in, or customize the viewVantage gate / VANTAGE_AUTH_ENABLED setting (explained below) if you need different behavior.

Retry Failed Jobs

php artisan vantage:retry {job_id}

Or use the web interface - just click retry on any failed job.

Programmatic Access

Vantage provides a convenient facade for easy programmatic access to queue monitoring data. The facade is automatically registered and ready to use:

use Storvia\Vantage\Facades\Vantage;

// Get queue depth for all queues
$depths = Vantage::queueDepth();

// Get failed jobs
$failedJobs = Vantage::failedJobs(limit: 100);

// Get jobs by tag
$emailJobs = Vantage::jobsByTag('email', limit: 50);

// Get statistics
$stats = Vantage::statistics(startDate: now()->subDays(7));
// Returns: ['total' => 1000, 'processed' => 950, 'failed' => 50, 'processing' => 0, 'success_rate' => 95.0]

// Retry a failed job programmatically
Vantage::retryJob($jobId);

// Clean up stuck jobs older than 24 hours
$cleaned = Vantage::cleanupStuckJobs(hoursOld: 24);

// Prune old jobs
$deleted = Vantage::pruneOldJobs(daysOld: 30);

// Check if Vantage is enabled
if (Vantage::enabled()) {
    // Monitor critical jobs
}

Available Facade Methods:

• queueDepth(?string $queue = null) - Get queue depths for all or specific queues
• jobsByStatus(string $status, int $limit = 50) - Get jobs by status (processing, processed, failed)
• failedJobs(int $limit = 50) - Get failed jobs
• processingJobs(int $limit = 50) - Get currently processing jobs
• jobsByTag(string $tag, int $limit = 50) - Get jobs filtered by tag
• statistics(?string $startDate = null) - Get dashboard statistics
• retryJob(int $jobId) - Retry a failed job programmatically
• cleanupStuckJobs(int $hoursOld = 24) - Clean up stuck processing jobs
• pruneOldJobs(int $daysOld = 30) - Prune old job records
• logger() - Get the VantageLogger instance
• enable() / disable() / enabled() - Control package state

Job Tagging

Jobs with tags (using Laravel's tags() method) are automatically tracked. Visit /vantage/tags to see:

• Tags Analytics: View statistics for all tags (total jobs, processed, failed, processing, success rate, average duration)
• Search: Filter tags by name in real-time
• Sortable Columns: Click any column header to sort by that metric
• Clickable Tags: Click a tag to view all jobs with that tag
• Time Filters: View data for last 24 hours, 7 days, or 30 days

Filter and view jobs by tag in the web interface.

Queue Depth Monitoring

Real-time queue depth tracking for all your queues. See how many jobs are pending in each queue with health status indicators.

Visit /vantage to see queue depths displayed with:

• Current pending job count per queue
• Health status (healthy/normal/warning/critical)
• Support for database and Redis queue drivers

Performance Telemetry

Vantage automatically tracks performance metrics for your jobs:

• Memory usage (start, end, peak)
• CPU time (user and system)
• Execution duration

Telemetry can be configured via environment variables (see Environment Variables section below).

Configuration

The config file should already be published during installation. If you need to republish it:

php artisan vendor:publish --tag=vantage-config

Main Settings

• store_payload - Whether to store job payloads (for debugging/retry)
• redact_keys - Keys to redact from payloads (password, token, etc.)
• retention_days - Default number of days to keep job history (used by vantage:prune command, default: 14)
• routes - Master switch to register dashboard routes
• route_prefix - Base URI segment for all dashboard routes (default: vantage)
• logging.enabled - Toggle Vantage's own log output
• notify.email - Email to notify on failures
• notify.slack_webhook - Slack webhook URL for failures
• telemetry.enabled - Enable performance telemetry (memory/CPU)
• telemetry.sample_rate - Sampling rate (0.0-1.0, default: 1.0)
• telemetry.capture_cpu - Enable CPU time tracking

Enable/Disable Package

To disable the package entirely (useful for staging environments):

VANTAGE_ENABLED=false

When disabled:

• No job tracking occurs
• Routes are not registered
• Event listeners are not active
• Commands are not registered
• No database writes
• Gate authorization is not registered

Perfect for testing in staging without affecting production data!

Multi-Database Support

If your application uses multiple databases, you can specify which database c