Logging

Come registrare il comportamento dell’applicazione su file, Slack e servizi esterni usando il sistema di logging di Laravel.

​

Cos’è il logging

Il logging di Laravel è progettato intorno al concetto di canali. Un canale è un’unità di configurazione che definisce dove e come scrivere i log. Puoi combinare file, Slack, syslog e altre destinazioni.

Internamente usa la libreria Monolog, sfruttando handler e formatter ricchi.

Di default viene usato il canale stack, un canale “genitore” che raggruppa più canali.

​

Configurazione

La configurazione del logging è in config/logging.php. La variabile d’ambiente LOG_CHANNEL cambia il canale predefinito.

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

​

Driver di canale disponibili

Driver	Descrizione
single	Scrive tutti i log in un unico file
daily	File per giorno (con rotazione)
slack	Invia messaggi a un Incoming Webhook di Slack
stack	Canale genitore che raggruppa più canali
syslog	Scrive su syslog di sistema
errorlog	Scrive nella error log di PHP
monolog	Usa direttamente handler Monolog
custom	Personalizza completamente con una classe factory

​

Livelli di log

Laravel supporta gli 8 livelli definiti in RFC 5424. In ordine di gravità decrescente:

Livello	Esempio d’uso
emergency	Sistema inutilizzabile; intervento immediato
alert	Deve intervenire subito un umano (es. DB disconnesso)
critical	Guasto grave con funzionalità principali ferme
error	Errore a runtime; intervento necessario ma non sempre immediato
warning	Problema potenziale (API deprecate, dati anomali)
notice	Funzionamento normale ma degno di nota
info	Operazioni ordinarie (login utente, ordine confermato)
debug	Informazioni dettagliate di debug in sviluppo

Il level di un canale è il livello minimo: se è error, solo error e superiori (critical, alert, emergency) vengono scritti.

​

Uso di base

​

Facade Log

Usa la facade Illuminate\Support\Facades\Log per scrivere ai vari livelli.

use Illuminate\Support\Facades\Log;

Log::emergency('Il sistema è fermo.');
Log::alert('Connessione al database persa.');
Log::critical('Il servizio di pagamento non risponde.');
Log::error('Aggiornamento dati utente fallito.');
Log::warning('Chiamato un metodo deprecato.');
Log::notice('File di configurazione ricaricato.');
Log::info('Utente autenticato.');
Log::debug('Tempo esecuzione query: 42ms');

Esempio in un controller.

<?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('Mostro il profilo utente.', ['user_id' => $id]);

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

​

Funzione helper log()

Con l’helper log() scrivi senza importare la facade Log.

log('Log dall\'helper.');

// Indica livello e contesto
log('Utente creato.', 'info', ['user_id' => $user->id]);

​

Aggiungere informazioni di contesto

Passando un array di contesto insieme al messaggio memorizzi informazioni correlate.

Log::info('Login fallito.', [
    'user_id' => $user->id,
    'ip'      => $request->ip(),
    'reason'  => 'Password errata',
]);

​

withContext() — contesto comune a livello di canale

Se vuoi che tutte le voci successive di un canale includano informazioni comuni (come un request ID) usa withContext().

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

// Da qui in poi tutti i log conterranno automaticamente request-id
Log::info('Inizio elaborazione.');
Log::error('Si è verificato un errore.');

​

shareContext() — contesto comune a tutti i canali

withContext() è limitato al canale bersaglio; shareContext() propaga il contesto a tutti i canali.

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

​

Configurazione dei canali

​

Canale stack — scrittura simultanea su più canali

Con stack scrivi in più canali con una sola chiamata.

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

Con questa configurazione tutti i log da debug in su vanno in daily (file) e solo quelli da critical in su vanno anche in Slack.

In produzione conviene impostare il livello del canale slack a error o critical. Con log leggeri finirebbero troppe notifiche e le alert importanti si perderebbero.

​

Canale daily — rotazione dei log

Il canale daily scrive file separati per giorno ed elimina automaticamente i più vecchi.

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

Riducendo days i log vecchi spariscono prima. Prevedi un periodo di ritenzione sufficiente per l’analisi dei problemi.

​

Notifica errori su Slack

Ottieni un Incoming Webhook URL e mettilo nel .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',
],

Includendo slack nel canale stack e impostando LOG_CHANNEL=stack ottieni la notifica automatica sugli errori.

​

Scrivere in un canale specifico

Con Log::channel() scegli esplicitamente il canale.

// Scrive solo su slack
Log::channel('slack')->error('Il servizio di pagamento non risponde.');

// Scrittura simultanea su più canali
Log::stack(['daily', 'slack'])->critical('Connessione DB fallita.');

​

Canali on-demand

Con Log::build() crei al volo un canale personalizzato senza definirlo nel file di configurazione. Utile per test o output temporanei.

use Illuminate\Support\Facades\Log;

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

Log::stack([$channel])->info('Inizio import CSV.');

​

Casi d’uso pratici

​

Assegnare un request ID in un middleware

Aggiungendo un request ID comune a tutti i log tracci più facilmente il flusso di una singola richiesta.

1. Crea il middleware

   php artisan make:middleware AssignRequestId
   
2. Implementa 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. Registra il middleware

   Registralo come middleware globale in bootstrap/app.php.

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

Dopo la configurazione, tutti i log conterranno automaticamente request-id.

[2026-03-01 12:00:00] local.INFO: Utente autenticato. {"request-id":"550e8400-...","user_id":1}
[2026-03-01 12:00:00] local.INFO: Mostro la dashboard. {"request-id":"550e8400-..."}

​

Log dei warning di deprecation

Puoi registrare i warning dovuti a funzionalità deprecate di PHP o Laravel.

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

Indica il canale nel .env.

LOG_DEPRECATIONS_CHANNEL=daily

​

Laravel Pail — monitoraggio log in tempo reale

Laravel Pail è uno strumento di sviluppo per vedere i log dell’applicazione in tempo reale dal terminale.

Per eseguire Pail serve l’estensione PHP PCNTL.

​

Installazione

composer require --dev laravel/pail

​

Uso di base

# Segui i log in scroll
php artisan pail

# Visualizzazione dettagliata (senza troncamenti)
php artisan pail -v

# Mostra anche lo stack trace
php artisan pail -vv

​

Filtro dei log

# Filtra per keyword
php artisan pail --filter="QueryException"

# Filtra solo per messaggio
php artisan pail --message="login"

# Filtra per livello
php artisan pail --level=error

# Mostra solo i log di un utente specifico
php artisan pail --user=1

​

Riepilogo

Come scegliere il livello

Livello	Quando usarlo
emergency	Guasti fatali che fermano tutto
alert	Deve intervenire subito una persona
critical	Guasti seri con funzioni principali ferme
error	Errori runtime imprevisti; intervento necessario
warning	Uso di funzionalità deprecate o dati inattesi
notice	Operazioni importanti da tracciare
info	Operazioni utente ed eventi di business
debug	Dettagli di debug in sviluppo (non serve in produzione)

Come scegliere i canali

• Sviluppo: single o daily su file
• Produzione: stack con daily (file) e slack (notifica errori)
• Log specifici: canale on-demand con Log::build() su file dedicato
• Monitoraggio real-time: php artisan pail dal terminale

Attenzioni in produzione

• I log debug possono contenere info sensibili. In produzione usa almeno LOG_LEVEL=error.
• Ruota i file periodicamente per non riempire il disco (opzione days del canale daily).
• Attenzione ai rate limit dei servizi esterni come Slack. Configura il livello per notificare solo gli errori gravi.