Logging - Knowledge of Laravel

Cos’è il logging

Il logging di Laravel è progettato attorno al concetto di channel. Un channel è l’unità di configurazione che definisce destinazione e modalità di scrittura dei log; puoi combinare file, Slack, syslog e altre destinazioni. Internamente usa la libreria Monolog, quindi hai a disposizione un’ampia gamma di handler e formatter.

Per default viene usato il channel stack. stack è un channel genitore che raggruppa più channel.

Configurazione

Tutta la configurazione del logging è centralizzata in config/logging.php. Il channel di default si cambia con la variabile d’ambiente LOG_CHANNEL.

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

Driver disponibili

Driver	Descrizione
`single`	Scrive tutti i log in un unico file
`daily`	Scrive un file per giorno (con rotazione)
`slack`	Invia messaggi a un Incoming Webhook di Slack
`stack`	Channel genitore che raggruppa più channel
`syslog`	Scrive sul syslog di sistema
`errorlog`	Scrive nell’error log di PHP
`monolog`	Indica direttamente un handler di Monolog
`custom`	Personalizzazione completa del channel tramite factory

Log level

Laravel supporta gli otto livelli di log definiti da RFC 5424. Sono elencati in ordine di gravità decrescente.

Livello	Esempio d’uso
`emergency`	Sistema completamente inutilizzabile. Serve azione immediata
`alert`	Situazione che richiede intervento umano immediato (es. DB down)
`critical`	Guasto critico che ferma funzionalità principali dell’app
`error`	Errore runtime; richiede intervento, non sempre immediato
`warning`	Potenziale problema. Uso di API deprecate, dati imprevisti ecc.
`notice`	Operazione normale ma da notare
`info`	Operazioni comuni: login, conferma ordini ecc.
`debug`	Informazioni di debug dettagliate in sviluppo

L’impostazione level di un channel indica il livello minimo. Se level è error, vengono scritti solo error e livelli superiori (critical, alert, emergency).

Uso di base

Facade Log

Con la facade Illuminate\Support\Facades\Log scrivi messaggi di ogni livello.

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("L'utente ha effettuato il login.");
Log::debug('Tempo di esecuzione query: 42ms');

Esempio d’uso 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("Visualizzazione del profilo utente.", ['user_id' => $id]);

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

La funzione helper log()

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

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

// puoi indicare anche livello e context
log('Utente creato.', 'info', ['user_id' => $user->id]);

Aggiungere informazioni di contesto

Passando un array di context insieme al messaggio, registri anche informazioni correlate.

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

withContext() — context comune al channel

Se vuoi allegare context comune a tutte le successive scritture di un channel specifico, usa withContext(). Utile per informazioni come il request ID che vuoi in tutti i log.

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

// request-id verrà incluso automaticamente in ogni log successivo
Log::info('Inizio elaborazione.');
Log::error('Si è verificato un errore.');

shareContext() — context comune a tutti i channel

Mentre withContext() è limitato al channel corrente, shareContext() distribuisce il context a tutti i channel.

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

Configurazione dei channel

Channel stack — scrittura simultanea su più channel

Il channel stack scrive con una sola chiamata su più channel.

// 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 su daily (file), mentre critical e superiori vanno anche su Slack.

In produzione conviene impostare il livello del channel slack su error o critical. Trasmettere anche i log meno rilevanti su Slack sommerge di notifiche e nasconde gli alert importanti.

Channel daily — rotazione dei log

Il channel daily divide i file per giorno e rimuove automaticamente i vecchi.

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

Un valore basso di days elimina prima i file più vecchi. In produzione mantieni una finestra sufficiente per l’analisi degli incidenti.

Notifiche di errore su Slack

Ottieni un Incoming Webhook URL di Slack e impostalo 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 channel stack e impostando LOG_CHANNEL=stack, verranno notificati automaticamente gli errori.

Scrivere su un channel specifico

Con Log::channel() puoi indicare esplicitamente il channel di destinazione.

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

// scrive contemporaneamente su più channel
Log::stack(['daily', 'slack'])->critical('Connessione al database fallita.');

Channel on-demand

Con Log::build() puoi creare al volo un channel personalizzato senza definirlo nel file di configurazione. Utile in test o per 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('Avvio dell\'importazione CSV.');

Casi d’uso pratici

Aggiungere un request ID tramite middleware

Aggiungendo un request ID a tutti i log, tracci 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);
})

Da questo momento, il request-id viene allegato automaticamente a tutti i log.

[2026-03-01 12:00:00] local.INFO: L'utente ha effettuato il login. {"request-id":"550e8400-...","user_id":1}
[2026-03-01 12:00:00] local.INFO: Visualizzazione della dashboard. {"request-id":"550e8400-..."}

Registrare gli avvisi di deprecation

Puoi conservare nei log gli avvisi generati dall’uso di funzionalità deprecate di PHP o Laravel.

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

Nel .env specifica il channel.

LOG_DEPRECATIONS_CHANNEL=daily

Laravel Pail — monitoraggio dei log in tempo reale

Laravel Pail è uno strumento di sviluppo che consente di visualizzare in terminale i log dell’applicazione in tempo reale. A differenza del classico comando tail, funziona con qualsiasi driver di log, incluso Laravel Nightwatch, Sentry e Flare.

Per eseguire Pail serve l’estensione PHP PCNTL.

Installazione

composer require --dev laravel/pail

Uso di base

# osserva il flusso dei log
php artisan pail

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

# mostra anche la stack trace
php artisan pail -vv

Filtro dei log

# filtra per parola chiave
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 di log

Livello	Quando usarlo
`emergency`	Guasto totale del sistema
`alert`	Richiede intervento umano immediato
`critical`	Le funzionalità principali non funzionano
`error`	Errore runtime imprevisto, va gestito
`warning`	Uso di API deprecate o dati inaspettati
`notice`	Operazione normale ma degna di traccia
`info`	Azioni utente o eventi business
`debug`	Dettagli di debug in sviluppo (non in produzione)

Guida alla scelta dei channel

Sviluppo: scrivi su file con single o daily
Produzione: usa stack combinando daily (file) e slack (notifica errori)
Log di elaborazioni specifiche: crea un channel on-demand con Log::build() per scrivere su un file dedicato
Monitoraggio real-time: usa php artisan pail dal terminale

Attenzioni in produzione

I log debug possono contenere dati sensibili. In produzione è consigliato LOG_LEVEL=error o superiore.
Ruota i file di log periodicamente per non riempire il disco (opzione days del channel daily).
Per le notifiche verso servizi esterni come Slack, attenzione ai rate limit: imposta il livello per notificare solo gli errori critici.

​Cos’è il logging

​Configurazione

​Driver disponibili

​Log level

​Uso di base

​Facade Log

​La funzione helper log()

​Aggiungere informazioni di contesto

​withContext() — context comune al channel

​shareContext() — context comune a tutti i channel

​Configurazione dei channel

​Channel stack — scrittura simultanea su più channel

​Channel daily — rotazione dei log

​Notifiche di errore su Slack

​Scrivere su un channel specifico

​Channel on-demand

​Casi d’uso pratici

​Aggiungere un request ID tramite middleware

​Registrare gli avvisi di deprecation

​Laravel Pail — monitoraggio dei log in tempo reale

​Installazione

​Uso di base

​Filtro dei log

​Riepilogo

Cos’è il logging

Configurazione

Driver disponibili

Log level

Uso di base

Facade Log

La funzione helper log()

Aggiungere informazioni di contesto

withContext() — context comune al channel

shareContext() — context comune a tutti i channel

Configurazione dei channel

Channel stack — scrittura simultanea su più channel

Channel daily — rotazione dei log

Notifiche di errore su Slack

Scrivere su un channel specifico

Channel on-demand

Casi d’uso pratici

Aggiungere un request ID tramite middleware

Registrare gli avvisi di deprecation

Laravel Pail — monitoraggio dei log in tempo reale

Installazione

Uso di base

Filtro dei log

Riepilogo