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

# 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](https://github.com/Seldaek/monolog), sfruttando handler e formatter ricchi.

<Info>
  Di default viene usato il canale `stack`, un canale "genitore" che raggruppa più canali.
</Info>

## Configurazione

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

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

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

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

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

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

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

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

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.

<Tip>
  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.
</Tip>

### Canale daily — rotazione dei log

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

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

<Warning>
  Riducendo `days` i log vecchi spariscono prima.
  Prevedi un periodo di ritenzione sufficiente per l'analisi dei problemi.
</Warning>

### Notifica errori su Slack

Ottieni un [Incoming Webhook URL](https://slack.com/apps/A0F7XDUAZ-incoming-webhooks) e mettilo nel `.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',
],
```

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.

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

```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('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.

<Steps>
  <Step title="Crea il middleware">
    ```shell theme={null}
    php artisan make:middleware AssignRequestId
    ```
  </Step>

  <Step title="Implementa 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="Registra il middleware">
    Registralo come middleware globale in `bootstrap/app.php`.

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

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.

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

Indica il canale nel `.env`.

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

## Laravel Pail — monitoraggio log in tempo reale

[Laravel Pail](https://github.com/laravel/pail) è uno strumento di sviluppo per vedere i log dell'applicazione in tempo reale dal terminale.

<Info>
  Per eseguire Pail serve l'estensione PHP [PCNTL](https://www.php.net/manual/en/book.pcntl.php).
</Info>

### Installazione

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

### Uso di base

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

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

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

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

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


## Related topics

- [Laravel Pulse](/it/pulse.md)
- [WebSocket (Jetstream / Firehose)](/it/packages/laravel-bluesky/websocket.md)
- [Gestione degli errori](/it/error-handling.md)
- [Aggiornamento da Laravel 9 a 10](/it/blog/upgrade-9-to-10.md)
- [Ciclo di vita della richiesta](/it/lifecycle.md)