Logging - Knowledge of 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.

Crea il middleware

php artisan make:middleware AssignRequestId

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

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.

​Cos’è il logging

​Configurazione

​Driver di canale disponibili

​Livelli di log

​Uso di base

​Facade Log

​Funzione helper log()

​Aggiungere informazioni di contesto

​withContext() — contesto comune a livello di canale

​shareContext() — contesto comune a tutti i canali

​Configurazione dei canali

​Canale stack — scrittura simultanea su più canali

​Canale daily — rotazione dei log

​Notifica errori su Slack

​Scrivere in un canale specifico

​Canali on-demand

​Casi d’uso pratici

​Assegnare un request ID in un middleware

​Log dei warning di deprecation

​Laravel Pail — monitoraggio log in tempo reale

​Installazione

​Uso di base

​Filtro dei log

​Riepilogo

Cos’è il logging

Configurazione

Driver di canale disponibili

Livelli di log

Uso di base

Facade Log

Funzione helper log()

Aggiungere informazioni di contesto

withContext() — contesto comune a livello di canale

shareContext() — contesto comune a tutti i canali

Configurazione dei canali

Canale stack — scrittura simultanea su più canali

Canale daily — rotazione dei log

Notifica errori su Slack

Scrivere in un canale specifico

Canali on-demand

Casi d’uso pratici

Assegnare un request ID in un middleware

Log dei warning di deprecation

Laravel Pail — monitoraggio log in tempo reale

Installazione

Uso di base

Filtro dei log

Riepilogo