Journalisation

Utilisation du système de journalisation de Laravel pour écrire les logs vers un fichier, Slack ou un service externe.

​

Qu’est-ce que la journalisation

La journalisation Laravel est conçue autour du concept de channels. Un channel est une unité de configuration qui définit où et comment écrire les logs : fichier, Slack, syslog… vous pouvez combiner plusieurs destinations.

En interne, Laravel utilise Monolog, avec ses nombreux handlers et formatters.

Par défaut, le channel stack est utilisé. stack regroupe plusieurs channels sous un channel parent.

​

Configuration

La configuration se trouve dans config/logging.php. La variable LOG_CHANNEL change le channel par défaut.

// config/logging.php
'default' => env('LOG_CHANNEL', 'stack'),

​

Drivers de channel disponibles

Driver	Description
single	Écrit toutes les logs dans un seul fichier
daily	Un fichier par jour (avec rotation)
slack	Envoie un message à un webhook entrant Slack
stack	Channel parent qui regroupe plusieurs channels
syslog	Écrit dans le syslog du système
errorlog	Écrit dans le journal d’erreurs de PHP
monolog	Spécifie directement un handler Monolog
custom	Personnalisation complète via une factory

​

Niveaux de log

Laravel supporte les 8 niveaux de RFC 5424, du plus grave au moins grave.

Niveau	Exemple d’usage
emergency	Système entier inutilisable, intervention immédiate
alert	État exigeant une intervention humaine immédiate (perte de connexion à la DB)
critical	Défaut grave où une fonctionnalité majeure ne fonctionne plus
error	Erreur d’exécution, à traiter (souvent sans urgence)
warning	Problème potentiel : API dépréciée, données inattendues
notice	Fonctionnement normal mais info à remonter
info	Log opérationnel : connexion, validation de commande
debug	Détails de débogage en développement

L’option level d’un channel indique le niveau minimum enregistré. Par exemple, level à error n’écrit que error et au-dessus (critical, alert, emergency).

​

Utilisation de base

​

Façade Log

Utilisez la façade Illuminate\Support\Facades\Log pour écrire chaque niveau.

use Illuminate\Support\Facades\Log;

Log::emergency('Le système est arrêté.');
Log::alert('Connexion à la base de données perdue.');
Log::critical('Le service de paiement ne répond pas.');
Log::error('Échec de la mise à jour des données utilisateur.');
Log::warning('Appel d\'une méthode dépréciée.');
Log::notice('Rechargement du fichier de configuration.');
Log::info('Utilisateur connecté.');
Log::debug('Durée de la requête : 42 ms');

Exemple dans un contrôleur :

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Support\Facades\Log;
use Illuminate\View\View;

class UserController extends Controller
{
    public function show(string $id): View
    {
        Log::info('Affichage du profil utilisateur.', ['user_id' => $id]);

        return view('user.profile', [
            'user' => User::findOrFail($id),
        ]);
    }
}

​

Helper log()

Le helper log() évite l’import de la façade Log.

log('Log depuis le helper.');

// Vous pouvez aussi spécifier niveau et contexte
log('Utilisateur créé.', 'info', ['user_id' => $user->id]);

​

Ajouter des données de contexte

Passez un tableau de contexte pour attacher des informations liées.

Log::info('Échec de connexion.', [
    'user_id' => $user->id,
    'ip'      => $request->ip(),
    'reason'  => 'mot de passe incorrect',
]);

​

withContext() — Contexte commun à un channel

Pour appliquer un contexte commun à tous les logs suivants d’un channel, utilisez withContext(). Idéal pour un identifiant de requête.

Log::withContext(['request-id' => (string) Str::uuid()]);

// Tous les logs suivants incluront request-id
Log::info('Début du traitement.');
Log::error('Erreur survenue.');

​

shareContext() — Contexte commun à tous les channels

withContext() ne s’applique qu’au channel visé ; shareContext() s’applique à tous les channels.

Log::shareContext(['app-version' => config('app.version')]);

​

Configuration des channels

​

Channel stack — écrire vers plusieurs channels

Le channel stack écrit vers plusieurs destinations en un seul appel.

// config/logging.php
'channels' => [
    'stack' => [
        'driver'   => 'stack',
        'channels' => ['daily', 'slack'],
    ],

    'daily' => [
        'driver' => 'daily',
        'path'   => storage_path('logs/laravel.log'),
        'level'  => env('LOG_LEVEL', 'debug'),
        'days'   => 14,
    ],

    'slack' => [
        'driver'   => 'slack',
        'url'      => env('LOG_SLACK_WEBHOOK_URL'),
        'username' => env('LOG_SLACK_USERNAME', 'Laravel Log'),
        'emoji'    => env('LOG_SLACK_EMOJI', ':boom:'),
        'level'    => 'critical',
    ],
],

Ici, tous les logs debug et supérieurs vont dans daily (fichier), mais seuls les critical et supérieurs partent vers slack.

En production, réglez le niveau du channel slack à error ou critical. Diffuser trop de logs sur Slack noie les alertes importantes.

​

Channel daily — rotation

daily crée un fichier par jour et supprime automatiquement les anciens.

'daily' => [
    'driver' => 'daily',
    'path'   => storage_path('logs/laravel.log'),
    'level'  => env('LOG_LEVEL', 'debug'),
    'days'   => env('LOG_DAILY_DAYS', 14), // Conservation 14 jours
],

Une valeur days trop basse supprime rapidement les anciens fichiers. Prévoyez une durée suffisante pour l’analyse post-incident.

​

Notifications d’erreur Slack

Récupérez une URL de Incoming Webhook Slack et placez-la dans .env.

LOG_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxx/yyy/zzz

// config/logging.php
'slack' => [
    'driver'   => 'slack',
    'url'      => env('LOG_SLACK_WEBHOOK_URL'),
    'username' => 'Laravel Error Bot',
    'emoji'    => ':fire:',
    'level'    => 'error',
],

Incluez slack dans stack et définissez LOG_CHANNEL=stack : les erreurs déclenchent une notification automatique.

​

Écrire dans un channel précis

Log::channel() cible explicitement un channel.

// Uniquement dans slack
Log::channel('slack')->error('Le service de paiement ne répond pas.');

// Vers plusieurs channels
Log::stack(['daily', 'slack'])->critical('Échec de connexion à la base de données.');

​

Channels à la demande

Log::build() crée un channel personnalisé à la volée, sans le déclarer dans la configuration. Pratique pour des sorties temporaires ou lors des tests.

use Illuminate\Support\Facades\Log;

$channel = Log::build([
    'driver' => 'single',
    'path'   => storage_path('logs/import-' . now()->format('Ymd') . '.log'),
]);

Log::stack([$channel])->info('Démarrage de l\'import CSV.');

​

Cas d’usage pratique

​

Attribuer un ID de requête via un middleware

Attribuer un ID commun à tous les logs facilite le suivi d’une requête donnée.

1. Créer le middleware

   php artisan make:middleware AssignRequestId
   
2. Implémenter `handle()`

   <?php
   
   namespace App\Http\Middleware;
   
   use Closure;
   use Illuminate\Http\Request;
   use Illuminate\Support\Facades\Log;
   use Illuminate\Support\Str;
   use Symfony\Component\HttpFoundation\Response;
   
   class AssignRequestId
   {
       public function handle(Request $request, Closure $next): Response
       {
           $requestId = (string) Str::uuid();
   
           Log::withContext(['request-id' => $requestId]);
   
           $response = $next($request);
   
           $response->headers->set('X-Request-Id', $requestId);
   
           return $response;
       }
   }
   
3. Enregistrer le middleware

   Enregistrez-le comme middleware global dans bootstrap/app.php.

   ->withMiddleware(function (Middleware $middleware) {
       $middleware->append(\App\Http\Middleware\AssignRequestId::class);
   })
   

Tous les logs incluent désormais request-id.

[2026-03-01 12:00:00] local.INFO: Utilisateur connecté. {"request-id":"550e8400-...","user_id":1}
[2026-03-01 12:00:00] local.INFO: Affichage du dashboard. {"request-id":"550e8400-..."}

​

Journaliser les avertissements de dépréciation

Journalisez les avertissements liés à l’usage de fonctionnalités dépréciées de PHP ou Laravel.

// config/logging.php
'deprecations' => [
    'channel' => env('LOG_DEPRECATIONS_CHANNEL', 'null'),
    'trace'   => env('LOG_DEPRECATIONS_TRACE', false),
],

Spécifiez le channel dans .env.

LOG_DEPRECATIONS_CHANNEL=daily

​

Laravel Pail — Suivi en temps réel

Laravel Pail est un outil de développement qui affiche les logs de l’application en temps réel dans le terminal.

Pail nécessite l’extension PHP PCNTL.

​

Installation

composer require --dev laravel/pail

​

Utilisation

# Suivre les logs en flux
php artisan pail

# Affichage détaillé (sans troncature)
php artisan pail -v

# Avec stack trace
php artisan pail -vv

​

Filtrage

# Par mot-clé
php artisan pail --filter="QueryException"

# Sur le message uniquement
php artisan pail --message="connexion"

# Par niveau
php artisan pail --level=error

# Uniquement pour un utilisateur
php artisan pail --user=1

​

Récapitulatif

Comment choisir un niveau de log

Niveau	Quand l’utiliser
emergency	Défaillance catastrophique de tout le système
alert	État qui impose une intervention humaine immédiate
critical	Défaillance majeure d’une fonctionnalité importante
error	Erreur d’exécution nécessitant une correction
warning	Usage déprécié ou données inattendues
notice	Fonctionnement normal, mais à consigner
info	Actions utilisateur ou événements métier
debug	Détails pendant le développement (inutile en production)

Guide de choix des channels

• Développement : écrire en fichier via single ou daily
• Production : combiner daily (persistance fichier) et slack (alertes) via stack
• Traitement spécifique : Log::build() pour un fichier dédié
• Suivi temps réel : php artisan pail dans le terminal

Précautions en production

• Les logs debug peuvent contenir des informations sensibles. En production, LOG_LEVEL=error ou plus est recommandé.
• Faites tourner régulièrement les fichiers de logs pour ne pas saturer le disque (option days du channel daily).
• Attention aux limites de taux des services externes comme Slack. Ne remontez que les erreurs critiques.