DOCSEARCHbyAlgolia
Submit Docs

Vantage for Laravel

repository·main·Indexed 42 days ago

https://github.com/storviaio/vantage

A Laravel package for tracking, monitoring, and debugging queue jobs across all drivers. It provides a web dashboard, persistent execution history, and performance telemetry for memory and CPU usage. Features include a programmatic facade for queue depth and statistics, CLI tools for retrying failed jobs and pruning old records, and support for Laravel 10.x through 13.x.

Tokens
9K
Snippets
39
Records
44
Agent score
54%

What's inside Vantage

  1. How Vantage job tracking works

    main

    Vantage works by listening to Laravel's internal queue events. This allows it to support any Laravel queue driver (Database, Redis, SQS, Beanstalkd, etc.) without requiring driver-specific implementations.

    Every job execution is recorded in the vantage_jobs table, capturing:

    • Job class, queue, and connection
    • Status (processing, processed, failed)
    • Timing (start, finish, duration)
    • A unique UUID to track the job across multiple retry attempts
    • Performance telemetry (Memory usage, CPU time)
    • Failure details (Exception class, message, and stack trace)
    • The full job payload and associated tags

  2. Install Vantage in Laravel

    main

    To install Vantage, require the package via Composer, publish the configuration file, and run the migrations to create the necessary tracking tables in your database.

    Installation Steps

    1. Install the package:
      composer require storviaio/vantage
    2. Publish the configuration:
      php artisan vendor:publish --tag=vantage-config
    3. Run migrations:
      php artisan migrate

    Publishing Assets

    • Config: php artisan vendor:publish --tag=vantage-config
    • Views (optional customization): php artisan vendor:publish --tag=vantage-views
    • Migrations: Automatically loaded, or publish via php artisan vendor:publish --tag=vantage-migrations
    composer require storviaio/vantage
php artisan vendor:publish --tag=vantage-config
php artisan migrate

  4. Schedule automatic job pruning

    main

    To maintain database health, schedule the vantage:prune command in your Laravel application's scheduler. Use the --force flag to allow unattended execution and --keep-processing to avoid deleting active jobs.

    protected function schedule(Schedule $schedule)
{
    // Prune jobs older than retention_days config
    $schedule->command('vantage:prune --force --keep-processing')
        ->daily()
        ->at('02:00');
}

  5. Disable the Vantage package

    main

    To disable Vantage entirely (e.g., in staging environments to avoid affecting production data), set the VANTAGE_ENABLED environment variable to false.

    When disabled:

    • No job tracking occurs.
    • Routes are not registered.
    • Event listeners are not active.
    • Commands are not registered.
    • No database writes occur.
    • Gate authorization is not registered.
    VANTAGE_ENABLED=false

  6. Customize dashboard authentication via the viewVantage gate

    main

    Vantage protects the dashboard using Laravel's Gate system via the viewVantage gate.

    • Default behavior: Any authenticated user can access the dashboard.
    • To disable authentication: Set VANTAGE_AUTH_ENABLED=false (not recommended for production).
    • To customize access: Override the viewVantage gate in your AppServiceProvider to implement custom logic (e.g., restricting access to admins).
    use Illuminate\Support\Facades\Gate;

public function boot(): void
{
    Gate::define('viewVantage', function ($user = null) {
        // Only allow admins
        return optional($user)->isAdmin();
    });
}

  7. Access the Vantage Web Interface

    main

    Vantage provides a comprehensive dashboard for monitoring your queue system. By default, the dashboard requires authentication.

    Dashboard Routes

    • Main Dashboard (/vantage): Provides high-level statistics (total jobs, success rates), queue depth monitoring with health status, top failing jobs, and recent job/batch activity.
    • Jobs List (/vantage/jobs): Advanced filtering for jobs by status, queue, job class, tags, and date range.
    • Failed Jobs (/vantage/failed): View failed jobs with full exception details and retry options.
    • Tags Analytics (/vantage/tags): View performance metrics (duration, success rate, etc.) for specific job tags.
    • Job Details (/vantage/jobs/{id}): Deep dive into a specific job, including payload, UUID, timing, exception stack traces, and the full retry chain.

    Note: You can customize authentication behavior using the viewVantage gate or the VANTAGE_AUTH_ENABLED setting.

  8. Configure multi-database support for Vantage

    main

    If your application uses multiple databases, you can specify which connection Vantage should use to store job runs. This ensures the vantage_jobs table is created and accessed from the correct connection. You can point Vantage to a dedicated database to keep monitoring data separate from application data.

    VANTAGE_DATABASE_CONNECTION=mysql

  9. Configure Vantage settings

    main

    Vantage configuration is managed via a published config file. If the file is missing, you can republish it using the Artisan command.

    Key configuration options include:

    • store_payload: Whether to store job payloads (useful for debugging/retries).
    • redact_keys: List of keys to redact from payloads (e.g., password, token).
    • retention_days: Number of days to keep job history (default: 14).
    • routes: Master switch to register dashboard routes.
    • route_prefix: Base URI segment for dashboard routes (default: vantage).
    • logging.enabled: Toggle Vantage's own log output.
    • notify.email: Email address for failure notifications.
    • notify.slack_webhook: Slack webhook URL for failure notifications.
    • 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.
    php artisan vendor:publish --tag=vantage-config

  10. Use VantageJob factory for testing

    main

    Vantage provides a model factory for Storvia\Vantage\Models\VantageJob to help create test data for various job states, tags, queues, and retry chains.

    use Storvia\Vantage\Models\VantageJob;

// Create test jobs
$job = VantageJob::factory()->create();

// Create specific job states
$failedJob = VantageJob::factory()->failed()->create();
$processingJob = VantageJob::factory()->processing()->create();
$processedJob = VantageJob::factory()->processed()->create();

// Create jobs with tags
$taggedJob = VantageJob::factory()
    ->withTags(['email', 'notification'])
    ->create();

// Create jobs on specific queues
$highPriorityJob = VantageJob::factory()
    ->onQueue('high')
    ->create();

// Create a retry chain
$originalJob = VantageJob::factory()->failed()->create();
$retryJob = VantageJob::factory()
    ->retriedFrom($originalJob->id)
    ->create();

// Create jobs with specific class names
$emailJob = VantageJob::factory()->jobClass('App\\Jobs\\SendEmailJob')->create();

  11. Exclude jobs from Vantage monitoring

    main

    You can prevent specific jobs from being tracked by Vantage using two methods:

    1. Config array: Add the job class to the exclude_jobs array in the Vantage configuration.
    2. Interface implementation: Implement the Storvia\Vantage\Contracts\ShouldNotBeTracked interface on your job class.
    // Method 1: Config
'exclude_jobs' => [
    App\Jobs\SomeNoisyJob::class,
],

// Method 2: Interface
use Storvia\Vantage\Contracts\ShouldNotBeTracked;

class MyNoisyJob implements ShouldQueue, ShouldNotBeTracked
{
    public function handle(): void { ... }
}

  12. Use the Vantage Facade for programmatic access

    main

    The Storvia\Vantage\Facades\Vantage facade allows you to interact with queue monitoring data directly from your application code.

    Common Methods

    • queueDepth(?string $queue = null): Returns queue depths for all or a specific queue.
    • failedJobs(int $limit = 50): Retrieves a list of failed jobs.
    • jobsByTag(string $tag, int $limit = 50): Retrieves jobs filtered by a specific tag.
    • statistics(?string $startDate = null): Returns an array of statistics (total, processed, failed, processing, success_rate).
    • retryJob(int $jobId): Retries a specific failed job.
    • cleanupStuckJobs(int $hoursOld = 24): Cleans up jobs stuck in 'processing' state.
    • pruneOldJobs(int $daysOld = 30): Deletes old job records from the database.
    • enable() / disable() / enabled(): Controls the package state.
    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
}