Logging - Knowledge of Laravel

Qu’est-ce que le logging ?

Le système de logging de Laravel s’articule autour de la notion de canaux (channels). Un canal est une unité de configuration qui définit où et comment les logs sont écrits. Vous pouvez combiner plusieurs destinations : fichiers, Slack, syslog, etc. En interne, Laravel utilise la bibliothèque Monolog et profite de ses nombreux handlers et formatters.

Par défaut, le canal stack est utilisé. stack est un canal parent qui regroupe plusieurs autres canaux.

Configuration

La configuration du logging est centralisée dans config/logging.php. La variable d’environnement LOG_CHANNEL permet de changer le canal par défaut.

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

Drivers de canal disponibles

Driver	Description
`single`	Écrit tous les logs dans un seul fichier
`daily`	Un fichier par jour, avec rotation
`slack`	Envoie les messages vers un Incoming Webhook Slack
`stack`	Canal parent qui regroupe plusieurs canaux
`syslog`	Écrit dans le syslog du système
`errorlog`	Écrit dans le log d’erreurs PHP
`monolog`	Utilise directement un handler Monolog
`custom`	Personnalisation complète via une classe factory

Niveaux de log

Laravel prend en charge les 8 niveaux définis par RFC 5424, classés du plus grave au moins grave.

Niveau	Exemples d’utilisation
`emergency`	Système entièrement inutilisable. Intervention immédiate.
`alert`	Intervention humaine immédiate (perte de connexion à la BDD…)
`critical`	Incident majeur, une fonctionnalité clé est HS
`error`	Erreur à l’exécution. Réaction requise, pas toujours immédiate
`warning`	Problème potentiel : API dépréciée, données inattendues, etc.
`notice`	Fonctionnement normal, mais info digne d’attention
`info`	Log d’opérations courantes : connexion utilisateur, validation d’une commande…
`debug`	Informations détaillées pour le développement

Le paramètre level d’un canal correspond au niveau minimum. Par exemple, si level vaut error, seuls les logs de niveau error ou supérieur (critical, alert, emergency) seront écrits.

Utilisation de base

La façade Log

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

use Illuminate\Support\Facades\Log;

Log::emergency('Le système est à l\'arrêt.');
Log::alert('La connexion à la base de données est interrompue.');
Log::critical('Le service de paiement ne répond pas.');
Log::error('Échec de la mise à jour des données utilisateur.');
Log::warning('Une méthode dépréciée a été appelée.');
Log::notice('Le fichier de configuration a été rechargé.');
Log::info('Un utilisateur s\'est connecté.');
Log::debug('Temps d\'exécution 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),
        ]);
    }
}

La fonction helper log()

Le helper log() évite d’importer la façade Log.

log('Log depuis le helper.');

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

Ajouter du contexte

En passant un tableau de contexte avec le message, vous regroupez les informations utiles associées.

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

withContext() — contexte partagé sur un canal

Utilisez withContext() pour attacher un contexte commun aux logs suivants sur un canal donné. C’est particulièrement adapté aux informations que vous voulez retrouver dans tous les logs, comme un identifiant de requête.

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

// Toutes les entrées de log suivantes incluront automatiquement request-id
Log::info('Démarrage du traitement.');
Log::error('Une erreur est survenue.');

shareContext() — contexte partagé sur tous les canaux

withContext() n’agit que sur le canal ciblé, alors que shareContext() propage le contexte à tous les canaux.

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

Configuration des canaux

Canal stack — écrire simultanément sur plusieurs canaux

Le canal stack écrit à chaque appel dans plusieurs canaux en une seule opération.

// 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',
    ],
],

Avec cette configuration, tous les logs de niveau debug ou supérieur sont écrits dans daily (fichier), et seuls les critical et plus sont également envoyés sur Slack.

En production, il est conseillé de fixer le niveau du canal slack à error ou critical. Faire remonter des logs mineurs sur Slack noie les alertes réellement importantes dans un flux de notifications.

Canal daily — rotation des logs

Le canal daily sépare les fichiers par date 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), // Conserver 14 jours
],

Une valeur days trop basse supprimera trop vite les anciens logs. Prévoyez une durée de rétention suffisante pour investiguer les incidents en production.

Notifier les erreurs sur Slack

Récupérez une URL d’Incoming Webhook Slack et déclarez-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',
],

Il suffit d’inclure slack dans le canal stack et de définir LOG_CHANNEL=stack pour que les erreurs soient notifiées automatiquement.

Écrire dans un canal spécifique

Log::channel() cible un canal explicitement.

// Écrire uniquement dans le canal slack
Log::channel('slack')->error('Le service de paiement ne répond pas.');

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

Canaux à la volée

Log::build() permet de créer un canal personnalisé sans l’ajouter au fichier de configuration. C’est utile pour les tests ou pour un fichier de log temporaire.

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 concrets

Attribuer un identifiant de requête via un middleware

Attribuer un identifiant commun à tous les logs facilite grandement le suivi du parcours d’une requête.

Créer le middleware

php artisan make:middleware AssignRequestId

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;
    }
}

Enregistrer le middleware

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

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

Après cette configuration, l’entrée request-id sera automatiquement présente dans tous les logs.

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

Loguer les alertes de dépréciation

Vous pouvez logger les avertissements liés aux fonctionnalités dépréciées de PHP ou de Laravel.

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

Précisez le canal dans .env.

LOG_DEPRECATIONS_CHANNEL=daily

Laravel Pail — supervision des logs en temps réel

Laravel Pail est un outil de développement qui affiche les logs de votre application en temps réel dans le terminal. Contrairement à tail, il fonctionne avec n’importe quel driver de log, y compris Laravel Nightwatch, Sentry ou Flare.

Pail requiert l’extension PHP PCNTL.

Installation

composer require --dev laravel/pail

Utilisation de base

# Suivre les logs
php artisan pail

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

# Afficher aussi la stack trace
php artisan pail -vv

Filtrage des logs

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

# Filtrer par contenu du message uniquement
php artisan pail --message="connexion"

# Filtrer par niveau de log
php artisan pail --level=error

# N'afficher que les logs d'un utilisateur
php artisan pail --user=1

Récapitulatif

Comment choisir le niveau de log

Niveau	Quand l’utiliser
`emergency`	Incident fatal touchant tout le système
`alert`	Situation nécessitant une intervention humaine immédiate
`critical`	Fonctionnalité principale hors service
`error`	Erreur d’exécution imprévue, à traiter
`warning`	Usage déprécié, données inattendues ou autres avertissements
`notice`	Événement normal mais digne d’être conservé
`info`	Événements métiers ou actions utilisateur
`debug`	Informations de développement détaillées (inutiles en production)

Guide de choix des canaux

Développement : single ou daily pour écrire dans un fichier.
Production : stack combinant daily (persistance) et slack (alertes).
Logs de traitement spécifique : créer un canal à la volée via Log::build() pour un fichier dédié.
Supervision temps réel : php artisan pail depuis le terminal.

Points d'attention en production

Les logs debug peuvent contenir des informations sensibles. En production, préférez LOG_LEVEL=error ou plus élevé.
Faites tourner régulièrement les fichiers pour éviter la saturation disque (paramètre days du canal daily).
Attention aux limites de débit des services externes comme Slack. Ne notifiez que les erreurs graves en configurant le niveau adéquat.

​Qu’est-ce que le logging ?

​Configuration

​Drivers de canal disponibles

​Niveaux de log

​Utilisation de base

​La façade Log

​La fonction helper log()

​Ajouter du contexte

​withContext() — contexte partagé sur un canal

​shareContext() — contexte partagé sur tous les canaux

​Configuration des canaux

​Canal stack — écrire simultanément sur plusieurs canaux

​Canal daily — rotation des logs

​Notifier les erreurs sur Slack

​Écrire dans un canal spécifique

​Canaux à la volée

​Cas d’usage concrets

​Attribuer un identifiant de requête via un middleware

​Loguer les alertes de dépréciation

​Laravel Pail — supervision des logs en temps réel

​Installation

​Utilisation de base

​Filtrage des logs

​Récapitulatif

Qu’est-ce que le logging ?

Configuration

Drivers de canal disponibles

Niveaux de log

Utilisation de base

La façade Log

La fonction helper log()

Ajouter du contexte

withContext() — contexte partagé sur un canal

shareContext() — contexte partagé sur tous les canaux

Configuration des canaux

Canal stack — écrire simultanément sur plusieurs canaux

Canal daily — rotation des logs

Notifier les erreurs sur Slack

Écrire dans un canal spécifique

Canaux à la volée

Cas d’usage concrets

Attribuer un identifiant de requête via un middleware

Loguer les alertes de dépréciation

Laravel Pail — supervision des logs en temps réel

Installation

Utilisation de base

Filtrage des logs

Récapitulatif