📜 Laravel Pail : tailler ses logs en temps réel, enfin

📚 Introduction

Pendant des années, “lire ses logs Laravel en local” voulait dire tail -f storage/logs/laravel.log, ouvrir le résultat dans less, et chercher l’aiguille dans la botte de foin. Sur un projet un peu actif, c’était inutilisable.

Laravel Pail change la donne. C’est un outil officiel, installable en quelques secondes, qui transforme le terminal en un tail interactif filtrable, conscient du format des logs Laravel, et capable d’afficher proprement les stack traces.

🚀 Installation et premier lancement

Pail requiert l’extension PHP PCNTL. Cela écarte Windows, mais reste sans souci sur macOS / Linux et dans la plupart des containers de dev.

L’installation tient en une commande :

composer require --dev laravel/pail

Et le lancement, en une autre :

php artisan pail
 
# Verbose : éviter les troncatures "…"
php artisan pail -v
 
# Verbose max : afficher les stack traces complètes
php artisan pail -vv

À partir de là, chaque log émis par l’application apparaît dans le terminal, formaté, coloré, avec le contexte étendu. Plus besoin de tail -f ni d’aller fouiller dans storage/logs/. Et contrairement à un tail -f qui ne lit qu’un fichier, Pail fonctionne avec n’importe quel driver de log (Sentry, Flare, Slack, syslog, stack…), parce qu’il écoute les événements de log de l’application, pas un fichier.

🔍 Les filtres qui font tout

Pail prend son sens dès qu’on apprend ses filtres. Les quatre disponibles :

# Par type, fichier, message OU contenu de la stack trace
php artisan pail --filter="QueryException"
php artisan pail --filter="SendInvoiceEmail"
 
# Uniquement les messages contenant "User created"
php artisan pail --message="User created"
 
# Par niveau de log (debug, info, notice, warning, error, critical, alert, emergency)
php artisan pail --level=error
php artisan pail --level=warning
 
# Uniquement les logs d'un utilisateur authentifié donné (par son ID)
php artisan pail --user=1

Les filtres se combinent, ce qui permet de cibler exactement le bruit qu’on veut entendre sans avoir à recompiler une commande grep à chaque fois.

🧠 Lecture des stack traces

Les exceptions étaient le grand sujet douloureux des fichiers laravel.log. Pail affiche les stack traces avec un formatage qui rend immédiatement lisible :

• Les fichiers et lignes en couleurs différenciées.
• Le code applicatif distingué du code vendor.
• Les variables locales contextualisées au niveau de la frame fautive.

Pour un développeur qui passe la moitié de sa journée à diagnostiquer des bugs, c’est probablement la fonctionnalité qui change le plus le quotidien.

🧰 Quand Pail s’arrête, où regarder ensuite

Pail est conçu pour le développement local et les sessions d’investigation rapides. En production, il ne remplace pas une stack d’observabilité comme SigNoz ou un agrégateur de logs distant. L’idée est plutôt :

• En local et en staging : Pail, parce que le feedback immédiat compte plus que la rétention longue durée.
• En production : OpenTelemetry → SigNoz (ou équivalent), parce que la corrélation logs / traces / métriques devient le sujet principal.

Pour un développeur qui veut un tour d’horizon des bonnes pratiques de logs côté Laravel, c’est aussi l’occasion de relire ses canaux de logs et de séparer proprement les flux applicatifs des flux d’audit.

🤖 Pail et les agents IA

Avec Laravel Boost, les logs deviennent un input intéressant pour un agent : analyser une exception, expliquer ce qui s’est passé, proposer un correctif. Pail facilite ce workflow parce qu’il produit en sortie un texte structuré et lisible, qu’on peut piper directement vers un assistant ou intégrer dans une session Claude Code.

C’est typiquement le genre d’enchaînement que je commence à mettre en place sur mes projets : laisser tourner Pail dans un onglet dédié avec un filtre serré, et copier-coller le snapshot vers l’agent au moment où une erreur survient :

php artisan pail --level=error -vv | tee storage/logs/pail-session.log

Et l’agent peut ensuite analyser le snapshot, le corréler avec le code, et proposer un fix testable. Avec Laravel Boost, la même information est même accessible directement via les outils MCP Last Error et Read Log Entries, sans copier-coller.

⚠️ Quelques bonnes pratiques

• Ajoutez Pail uniquement en require-dev : ce n’est pas un outil de production.
• Activez le format JSON de log dans Laravel pour bénéficier pleinement des filtres : Pail tire parti des champs structurés (level, context, request_id).
• Configurez un canal de log dédié pour le dev (stderr ou pail) plutôt que d’écrire dans storage/logs/laravel.log qui restera lu par d’autres outils.

🎉 Conclusion

Laravel Pail est un de ces petits outils qui font une grosse différence : pas de paradigme révolutionnaire, juste une expérience de logs locale enfin agréable. Sur les sessions de débogage, le gain de temps est mesurable dès la première heure.

Si vous travaillez sur Laravel et que vous n’avez pas encore installé Pail, c’est la prochaine commande à taper. C’est trivialement réversible et l’ergonomie change immédiatement.

🔗 Liens utiles

• Dépôt GitHub laravel/pail
• Documentation Laravel — Logging