> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/Seldaek/monolog), avec ses nombreux handlers et formatters.

<Info>
  Par défaut, le channel `stack` est utilisé. `stack` regroupe plusieurs channels sous un channel parent.
</Info>

## Configuration

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

```php theme={null}
// 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](https://tools.ietf.org/html/rfc5424), 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.

```php theme={null}
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 theme={null}
<?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`.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
// 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`.

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

### Channel `daily` — rotation

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

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

<Warning>
  Une valeur `days` trop basse supprime rapidement les anciens fichiers. Prévoyez une durée suffisante pour l'analyse post-incident.
</Warning>

### Notifications d'erreur Slack

Récupérez une URL de [Incoming Webhook Slack](https://slack.com/apps/A0F7XDUAZ-incoming-webhooks) et placez-la dans `.env`.

```ini theme={null}
LOG_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxx/yyy/zzz
```

```php theme={null}
// 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.

```php theme={null}
// 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.

```php theme={null}
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.

<Steps>
  <Step title="Créer le middleware">
    ```shell theme={null}
    php artisan make:middleware AssignRequestId
    ```
  </Step>

  <Step title="Implémenter `handle()`">
    ```php theme={null}
    <?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;
        }
    }
    ```
  </Step>

  <Step title="Enregistrer le middleware">
    Enregistrez-le comme middleware global dans `bootstrap/app.php`.

    ```php theme={null}
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->append(\App\Http\Middleware\AssignRequestId::class);
    })
    ```
  </Step>
</Steps>

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.

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

Spécifiez le channel dans `.env`.

```ini theme={null}
LOG_DEPRECATIONS_CHANNEL=daily
```

## Laravel Pail — Suivi en temps réel

[Laravel Pail](https://github.com/laravel/pail) est un outil de développement qui affiche les logs de l'application en temps réel dans le terminal.

<Info>
  Pail nécessite l'extension PHP [PCNTL](https://www.php.net/manual/fr/book.pcntl.php).
</Info>

### Installation

```shell theme={null}
composer require --dev laravel/pail
```

### Utilisation

```shell theme={null}
# 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

```shell theme={null}
# 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

<AccordionGroup>
  <Accordion title="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) |
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>


## Related topics

- [Créer un serveur MCP avec Laravel](/fr/advanced/mcp-server.md)
- [Collections](/fr/collections.md)
- [Laravel Pulse](/fr/pulse.md)
- [Événements](/fr/packages/laravel-copilot-sdk/events.md)
- [Middleware](/fr/middleware.md)