Vantage : Surveillez vos queues Laravel facilement

Le monitoring des queues Laravel reste un défi pour beaucoup de développeurs. Vantage, créé par Houda Slassi, offre une solution complète qui fonctionne avec tous les drivers de queue : Redis, SQS, Beanstalkd, database… et persiste les données en base pour une analyse approfondie.

Présentation de Vantage

Vantage est un package open source qui enregistre automatiquement l’historique d’exécution de vos jobs, les échecs, les retries et fournit une interface web intuitive. Contrairement à d’autres outils de monitoring, ce package ne se limite pas à un driver spécifique.

La version actuelle (v0.1.19, sortie le 26 novembre 2025) supporte Laravel 10.x, 11.x et 12.x avec PHP 8.1+. Le projet compte déjà plus de 190 étoiles sur GitHub après quelques semaines d’existence.

Drivers de bases de données compatibles :

MySQL 5.7+ / MariaDB 10.3+
PostgreSQL 9.6+
SQLite 3.8.8+

Installation et configuration

L’installation se fait en trois commandes :

# Installation du package via Composer
composer require houdaslassi/vantage

# Publication du fichier de configuration
php artisan vendor:publish --tag=vantage-config

# Exécution des migrations
php artisan migrate

Le package s’enregistre automatiquement grâce au système de découverte de Laravel. Une table vantage_jobs sera créée pour stocker l’historique des jobs.

Configuration via variables d’environnement

Voici les principales options disponibles dans votre fichier .env :

// Activer/désactiver entièrement le package
VANTAGE_ENABLED=true

// Connexion base de données (si multi-database)
VANTAGE_DATABASE_CONNECTION=mysql

// Activer l'authentification pour le dashboard
VANTAGE_AUTH_ENABLED=true

// Stocker les payloads des jobs (utile pour debug/retry)
VANTAGE_STORE_PAYLOAD=true

// Télémétrie (mémoire/CPU)
VANTAGE_TELEMETRY_ENABLED=true
VANTAGE_TELEMETRY_SAMPLE_RATE=1.0

// Rétention des données (en jours)
VANTAGE_RETENTION_DAYS=14

// Préfixe des routes du dashboard
VANTAGE_ROUTE_PREFIX=vantage

Le dashboard web

Accédez à /vantage pour visualiser le tableau de bord complet. Le dashboard affiche :

Statistiques globales : jobs totaux, traités, échoués, en cours, taux de réussite
Profondeur des queues : nombre de jobs en attente par queue avec indicateurs de santé
Graphique de tendance : visualisation succès/échecs dans le temps
Top des jobs défaillants : quelles classes échouent le plus
Exceptions fréquentes : types d’erreurs les plus courants

<?php

// Personnaliser l'accès au dashboard dans AppServiceProvider
use Illuminate\Support\Facades\Gate;

public function boot(): void
{
    Gate::define('viewVantage', function ($user = null) {
        // Autoriser uniquement les administrateurs
        return optional($user)->isAdmin();

        // Ou toute autre logique métier
        // return $user && $user->hasRole('developer');
    });
}

Le dashboard est protégé par défaut via le système Gate de Laravel. Seuls les utilisateurs authentifiés peuvent y accéder.

Suivi des jobs avec tags

Vantage exploite la méthode tags() native de Laravel pour catégoriser vos jobs. Les tags permettent un filtrage avancé et des statistiques par catégorie.

<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class ProcessInvoice implements ShouldQueue
{
    use InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(
        public int $invoiceId,
        public int $userId
    ) {}

    // Définir les tags pour le tracking Vantage
    public function tags(): array
    {
        return [
            'invoice:' . $this->invoiceId,
            'user:' . $this->userId,
            'billing',
        ];
    }

    public function handle(): void
    {
        // Logique de traitement de facture
    }
}

Rendez-vous sur /vantage/tags pour consulter les statistiques par tag : nombre total de jobs, taux de réussite, durée moyenne d’exécution.

Retry des jobs échoués

Deux options s’offrent à vous pour relancer un job en échec :

Via la ligne de commande :

# Relancer un job spécifique par son ID
php artisan vantage:retry {job_id}

Via l’interface web : cliquez sur le bouton « Retry » depuis la page de détails du job (/vantage/failed). L’interface affiche l’exception complète, la stack trace et le payload original.

Nettoyage automatique des données

Pour éviter une croissance excessive de la table vantage_jobs, utilisez la commande de purge :

<?php

// Dans app/Console/Kernel.php
protected function schedule(Schedule $schedule): void
{
    // Purger les jobs de plus de 14 jours (config par défaut)
    // --force évite la confirmation interactive
    // --keep-processing préserve les jobs en cours
    $schedule->command('vantage:prune --force --keep-processing')
        ->daily()
        ->at('02:00');
}

Options disponibles :

--days=30 : conserver les jobs des X derniers jours
--hours=12 : conserver les jobs des X dernières heures
--status=failed : purger uniquement les jobs échoués
--dry-run : prévisualiser sans supprimer

Télémétrie de performance

Vantage capture automatiquement des métriques de performance pour chaque job :

Utilisation mémoire (début, fin, pic)
Temps CPU (user et system)
Durée d’exécution

Ces données apparaissent dans la vue détaillée de chaque job. Vous pouvez ajuster le taux d’échantillonnage via VANTAGE_TELEMETRY_SAMPLE_RATE (valeur entre 0.0 et 1.0).

Nettoyage des jobs bloqués

Parfois, des jobs restent coincés en statut « processing » suite à un crash du worker. La commande suivante les nettoie :

# Marquer comme échoués les jobs bloqués depuis plus de 2 heures
php artisan vantage:cleanup-stuck --timeout=2

# Prévisualiser sans action
php artisan vantage:cleanup-stuck --dry-run

Points d’attention

Authentification requise : le dashboard nécessite un utilisateur connecté par défaut. Désactivez via VANTAGE_AUTH_ENABLED=false si besoin (déconseillé en production).
Multi-database : spécifiez VANTAGE_DATABASE_CONNECTION si vos données de monitoring doivent être séparées.
Désactivation en staging : utilisez VANTAGE_ENABLED=false pour éviter le tracking en environnement de test.
Rédaction sensible : configurez redact_keys dans config/vantage.php pour masquer les données sensibles (mots de passe, tokens).

Conclusion

Vantage comble un vide dans l’écosystème Laravel : un monitoring de queues universel, persistant et visuellement riche. Le projet est activement maintenu avec 22 releases en quelques semaines. Une alternative solide à Horizon pour ceux qui n’utilisent pas Redis, ou un complément pour une visibilité historique approfondie.