Journalisation - Knowledge of Laravel

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.

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

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.

​Qu’est-ce que la journalisation

​Configuration

​Drivers de channel disponibles

​Niveaux de log

​Utilisation de base

​Façade Log

​Helper log()

​Ajouter des données de contexte

​withContext() — Contexte commun à un channel

​shareContext() — Contexte commun à tous les channels

​Configuration des channels

​Channel stack — écrire vers plusieurs channels

​Channel daily — rotation

​Notifications d’erreur Slack

​Écrire dans un channel précis

​Channels à la demande

​Cas d’usage pratique

​Attribuer un ID de requête via un middleware

​Journaliser les avertissements de dépréciation

​Laravel Pail — Suivi en temps réel

​Installation

​Utilisation

​Filtrage

​Récapitulatif

Qu’est-ce que la journalisation

Configuration

Drivers de channel disponibles

Niveaux de log

Utilisation de base

Façade Log

Helper `log()`

Ajouter des données de contexte

`withContext()` — Contexte commun à un channel

`shareContext()` — Contexte commun à tous les channels

Configuration des channels

Channel `stack` — écrire vers plusieurs channels

Channel `daily` — rotation

Notifications d’erreur Slack

Écrire dans un channel précis

Channels à la demande

Cas d’usage pratique

Attribuer un ID de requête via un middleware

Journaliser les avertissements de dépréciation

Laravel Pail — Suivi en temps réel

Installation

Utilisation

Filtrage

Récapitulatif