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

# Laravel Pulse

> Introduzione e configurazione della dashboard di monitoraggio Laravel Pulse: recorder, sampling e card personalizzate.

## Cos'è Laravel Pulse

[Laravel Pulse](https://github.com/laravel/pulse) è una dashboard di monitoraggio che ti mostra a colpo d'occhio prestazioni e utilizzo dell'applicazione.
Individua job lenti, endpoint lenti e utenti più attivi.

### Differenza con Telescope

| Caratteristica  | Laravel Pulse              | Laravel Telescope                        |
| --------------- | -------------------------- | ---------------------------------------- |
| Scopo           | Trend e metriche aggregate | Debug dettagliato di richieste ed eventi |
| Dati            | Metriche aggregate         | Log per singolo evento                   |
| Ambiente ideale | Produzione                 | Sviluppo/staging                         |

<Info>
  Per il debug dettagliato di singoli eventi usa [Laravel Telescope](/it/blog/telescope-introduction).
</Info>

### Flusso dei dati

```mermaid theme={null}
flowchart LR
    A["App Laravel"] -->|Rileva eventi| B["Recorder"]
    B -->|Registra entry| C["Database<br>(tabelle Pulse)"]
    C -->|Aggrega e mostra| D["Dashboard<br>/pulse"]
    E["Demone<br>pulse:check"] -->|Info server| C
```

***

## Installazione

<Warning>
  Lo storage first-party richiede MySQL, MariaDB o PostgreSQL. Se usi altro DB, predisponi un DB dedicato.
</Warning>

<Steps>
  <Step title="Pacchetto">
    ```shell theme={null}
    composer require laravel/pulse
    ```
  </Step>

  <Step title="Pubblica config e migration">
    ```shell theme={null}
    php artisan vendor:publish --provider="Laravel\Pulse\PulseServiceProvider"
    ```
  </Step>

  <Step title="Migrate">
    ```shell theme={null}
    php artisan migrate
    ```
  </Step>
</Steps>

Dashboard: `/pulse`.

### Pubblicare solo la config

```shell theme={null}
php artisan vendor:publish --tag=pulse-config
```

***

## Accesso alla dashboard

### Autenticazione

Di default solo `local`. Definisci la gate `viewPulse` in `AppServiceProvider`.

```php theme={null}
use App\Models\User;
use Illuminate\Support\Facades\Gate;

public function boot(): void
{
    Gate::define('viewPulse', function (User $user) {
        return $user->isAdmin();
    });
}
```

### Personalizzazione

```shell theme={null}
php artisan vendor:publish --tag=pulse-dashboard
```

Modifica `resources/views/vendor/pulse/dashboard.blade.php`. La dashboard è [Livewire](https://livewire.laravel.com/), niente build JS.

```blade theme={null}
<x-pulse full-width>
    ...
</x-pulse>

<x-pulse cols="16">
    ...
</x-pulse>
```

`cols` e `rows` regolano dimensioni e posizione.

```blade theme={null}
<livewire:pulse.usage cols="4" rows="2" />
<livewire:pulse.slow-queries expand />
```

***

## Recorder

Registrano gli eventi. Configurazione in `config/pulse.php` sezione `recorders`.

### Requests / Slow Requests

Cattura info sulle richieste. Soglia di route lente (default 1000ms), sample rate, path da ignorare.

```php theme={null}
Recorders\SlowRequests::class => [
    // ...
    'threshold' => [
        '#^/admin/#' => 5000,
        'default' => env('PULSE_SLOW_REQUESTS_THRESHOLD', 1000),
    ],
],
```

### Slow Jobs

```php theme={null}
Recorders\SlowJobs::class => [
    // ...
    'threshold' => [
        '#^App\\Jobs\\GenerateYearlyReports$#' => 5000,
        'default' => env('PULSE_SLOW_JOBS_THRESHOLD', 1000),
    ],
],
```

### Exceptions

Cattura eccezioni segnalabili. Raggruppate per classe e posizione.

### Cache

Hit/miss della cache.

```php theme={null}
Recorders\CacheInteractions::class => [
    // ...
    'groups' => [
        '/:\d+/' => ':*',
    ],
],
```

### Queues

Throughput dei job (in coda, in elaborazione, completati, rilasciati, falliti).

### Servers

CPU, memoria, storage. Richiede `pulse:check` in esecuzione su ogni server.

```shell theme={null}
php artisan pulse:check
```

Nome server con variabile d'ambiente:

```ini theme={null}
PULSE_SERVER_NAME=load-balancer
```

### Users

`UserRequests` e `UserJobs` catturano info utente per la card "Application Usage".

### Redis Ingest

Per alto traffico invia le entry a uno stream Redis prima di scriverle in DB.

```ini theme={null}
PULSE_INGEST_DRIVER=redis
```

Serve il worker:

```shell theme={null}
php artisan pulse:work
```

***

## Sampling

In produzioni ad alto traffico, con il sampling registri solo una parte degli eventi.

```php theme={null}
Recorders\UserRequests::class => [
    'sample_rate' => 0.1, // 10%
],
```

Nella dashboard il valore approssimato è preceduto da `~`.

***

## Variabili d'ambiente

| Variabile                       | Descrizione                      | Default          |
| ------------------------------- | -------------------------------- | ---------------- |
| `PULSE_ENABLED`                 | Attivo/disattivo                 | `true`           |
| `PULSE_DB_CONNECTION`           | Connessione DB                   | Default dell'app |
| `PULSE_INGEST_DRIVER`           | Driver di ingest (`redis`, ecc.) | `storage`        |
| `PULSE_SERVER_NAME`             | Nome server                      | `gethostname()`  |
| `PULSE_SLOW_REQUESTS_THRESHOLD` | Soglia richieste lente (ms)      | `1000`           |
| `PULSE_SLOW_JOBS_THRESHOLD`     | Soglia job lenti (ms)            | `1000`           |
| `PULSE_SLOW_QUERIES_THRESHOLD`  | Soglia query lente (ms)          | `1000`           |

***

## Card personalizzate

Card come componenti Livewire.

```php theme={null}
namespace App\Livewire\Pulse;

use Laravel\Pulse\Livewire\Card;
use Livewire\Attributes\Lazy;

#[Lazy]
class TopSellers extends Card
{
    public function render()
    {
        return view('livewire.pulse.top-sellers');
    }
}
```

Vista con i componenti Blade di Pulse:

```blade theme={null}
<x-pulse::card :cols="$cols" :rows="$rows" :class="$class" wire:poll.5s="">
    <x-pulse::card-header name="Top Sellers">
        <x-slot:icon>
            ...
        </x-slot:icon>
    </x-pulse::card-header>

    <x-pulse::scroll :expand="$expand">
        ...
    </x-pulse::scroll>
</x-pulse::card>
```

Cattura dati custom con `Pulse::record`.

```php theme={null}
use Laravel\Pulse\Facades\Pulse;

Pulse::record('user_sale', $user->id, $sale->amount)
    ->sum()
    ->count();
```

Aggiungi la card alla dashboard:

```blade theme={null}
<x-pulse>
    ...
    <livewire:pulse.top-sellers cols="4" />
</x-pulse>
```

***

## Riepilogo

| Obiettivo                       | Metodo                                  |
| ------------------------------- | --------------------------------------- |
| Installazione                   | `composer require laravel/pulse`        |
| Accesso dashboard               | Route `/pulse`                          |
| Controllo accessi in produzione | Gate `viewPulse`                        |
| Monitor server                  | `php artisan pulse:check` sempre attivo |
| Sampling                        | Opzione `sample_rate`                   |

## Prossimi passi

<Columns cols={2}>
  <Card title="Gestione errori" icon="circle-x" href="/it/error-handling">
    Gestione delle eccezioni.
  </Card>

  <Card title="Logging" icon="file-text" href="/it/logging">
    Configurazione e uso del logging.
  </Card>
</Columns>


## Related topics

- [Laravel Reverb](/it/reverb.md)
- [Laravel Pennant](/it/pennant.md)
- [Laravel Telescope](/it/telescope.md)
- [Tecniche pratiche di Laravel Telescope](/it/blog/telescope-introduction.md)
- [Introduzione a Laravel Nightwatch](/it/blog/nightwatch-introduction.md)