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

# Recorder Pulse personalizzati nei package

> Scopri come usare i recorder di Laravel Pulse per aggregare nella dashboard gli eventi specifici di un package. Vengono trattati la sottoscrizione con listen, l'aggregazione con Pulse::record, le impostazioni ignore e sample_rate e la gestione delle eccezioni.

Laravel Pulse aggrega nella dashboard richieste, query, job e altro. Quando il tuo package svolge un proprio lavoro, un recorder personalizzato ti permette di monitorare in Pulse il numero e la durata di quel lavoro.

Questa guida costruisce un recorder che si iscrive a un evento emesso da un package e ne registra numero e durata. Per l'uso di base di Pulse, consulta [Pulse](https://kawax.biz/it/pulse.md).

> [!NOTE]
>
> Questa guida si basa sul codice sorgente di Pulse 1.11.0. L'evento `ReportGenerated` negli esempi è una classe ipotetica a scopo illustrativo. In un package reale, sostituiscilo con il tuo evento.

## Come funziona

Quando un recorder riceve un evento, aggiunge record al buffer di Pulse. Il buffer viene salvato in blocco al momento dell'ingest.

```mermaid theme={null}
flowchart LR
    A["Evento emesso"] --> B["listen chiama<br>record"]
    B --> C["Pulse::record<br>crea un Entry"]
    C --> D["Buffer di Pulse"]
    D --> E["Salvato all'ingest"]
    E --> F["pulse_entries"]
    E --> G["pulse_aggregates"]
    F --> H["Mostrato nella dashboard"]
    G --> H
```

## Creare un recorder

Un recorder dichiara gli eventi a cui iscriversi nella proprietà `listen` e implementa il lavoro nel metodo `record()`. L'esempio seguente registra l'evento `ReportGenerated` emesso da un package. Si assume che l'evento abbia le proprietà `$type` e `$durationMs`.

```php theme={null}
<?php

namespace Acme\Reports\Pulse;

use Acme\Reports\Events\ReportGenerated;
use Laravel\Pulse\Facades\Pulse;
use Laravel\Pulse\Recorders\Concerns\Ignores;
use Laravel\Pulse\Recorders\Concerns\Sampling;

class ReportGenerationRecorder
{
    use Ignores, Sampling;

    public array $listen = [
        ReportGenerated::class,
    ];

    public function record(ReportGenerated $event): void
    {
        if ($this->shouldIgnore($event->type) || ! $this->shouldSample()) {
            return;
        }

        Pulse::record(
            type: 'report_generation',
            key: $event->type,
            value: $event->durationMs,
        )->count()->avg()->max();
    }
}
```

I trait `Ignores` e `Sampling` leggono le impostazioni `ignore` e `sample_rate` descritte più avanti.

## Registrare il recorder nell'applicazione

Registra il recorder nell'array `recorders` del file `config/pulse.php` dell'applicazione. Usa il nome della classe del recorder come chiave e specifica come valore il flag di attivazione e le impostazioni.

```php theme={null}
'recorders' => [
    // Mantieni invariati i recorder esistenti
    Acme\Reports\Pulse\ReportGenerationRecorder::class => [
        'enabled' => true,
        'sample_rate' => 1,
        'ignore' => ['/^debug_/'],
    ],
],
```

`PulseServiceProvider` carica `pulse.recorders` e registra i recorder quando `pulse.enabled` è attivo. Un recorder con `enabled` impostato a `false` non viene registrato. Invece di riscrivere automaticamente questa impostazione dal package, è più sicuro mostrare l'esempio di configurazione nelle istruzioni di installazione.

## Tipi di aggregazione

`Pulse::record()` restituisce un `Entry`. Concatenando `count()`, `min()`, `max()`, `sum()` o `avg()`, l'aggregato corrispondente viene salvato in `pulse_aggregates`.

| Metodo | Valore salvato |
| - | - |
| `count()` | Conteggio |
| `min()` | Valore minimo |
| `max()` | Valore massimo |
| `sum()` | Somma |
| `avg()` | Media |
| `onlyBuckets()` | Salva solo i risultati aggregati, senza record individuali in `pulse_entries` |

`min()`, `max()`, `sum()` e `avg()` usano `value` nel calcolo. `count()` da solo non richiede `value`.

Quando un evento si verifica molto spesso, `onlyBuckets()` riduce il numero di righe in `pulse_entries`.

## Salvare un valore stringa

Quando vuoi salvare una stringa, come lo stato più recente, invece di aggregare un numero, usa `Pulse::set()`. Il valore viene salvato nella tabella `pulse_values`.

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

Pulse::set('report_status', $event->type, $event->status);
```

Il `value` deve essere passato come `string`.

## Rimandare il lavoro oneroso

La closure passata a `Pulse::lazy()` non viene eseguita subito. Viene eseguita quando Pulse acquisisce i dati. Usala quando la registrazione richiede tempo e vuoi che venga eseguita dopo l'invio della risposta.

```php theme={null}
Pulse::lazy(function () use ($event) {
    Pulse::record('report_size', $event->type, $event->rows)->sum();
});
```

## Registrare l'utente autenticato

Quando ti serve l'identificatore dell'utente autenticato, usa `Pulse::resolveAuthenticatedUserId()`. Restituisce `null` quando nessun utente è autenticato.

```php theme={null}
$userId = Pulse::resolveAuthenticatedUserId();
```

## Ignorare, campionare e filtrare

Usa questi quattro strumenti per ridurre ciò che viene registrato:

* Impostazione `ignore`: salta la registrazione quando il valore passato a `shouldIgnore()` corrisponde a una delle espressioni regolari. Nell'esempio sopra, vengono saltati gli eventi il cui `$event->type` corrisponde a `/^debug_/`.
* Impostazione `sample_rate`: verificata da `shouldSample()`. `1` registra ogni evento e `0.1` circa il 10%.
* `Pulse::ignore()`: disattiva la registrazione all'interno della callback e restituisce il risultato della callback.
* `Pulse::filter()`: riceve ogni `Entry` o `Value` prima del salvataggio e salva solo gli elementi per cui restituisce `true`.

## Gestione delle eccezioni

Pulse racchiude il lavoro dei recorder e l'ingest in `rescue()`. Le eccezioni lanciate all'interno di un recorder non raggiungono la tua applicazione. Se `handleExceptionsUsing()` non è impostato, l'eccezione viene scartata silenziosamente. Per segnalare le eccezioni, configuralo nella tua applicazione.

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

Pulse::handleExceptionsUsing(fn (Throwable $e) => report($e));
```

## Test

Per testare un recorder, puoi emettere l'evento, chiamare `Pulse::ingest()` e verificare la riga salvata. L'esempio seguente è derivato dal codice sorgente di Pulse e non è stato eseguito. Assicurati che `pulse.enabled` sia attivo nel tuo ambiente di test.

```php theme={null}
use Acme\Reports\Events\ReportGenerated;
use Laravel\Pulse\Facades\Pulse;

it('records ReportGenerated in pulse_entries', function () {
    event(new ReportGenerated(type: 'monthly', durationMs: 120));

    Pulse::ingest();

    $this->assertDatabaseHas('pulse_entries', [
        'type' => 'report_generation',
        'key' => 'monthly',
        'value' => 120,
    ]);
});
```

## Progettare le chiavi

`key` è l'unità di aggregazione. Se usi valori che crescono senza limiti, come ID utente o URL, il volume di dati aumenta e gli aggregati diventano difficili da leggere. Usa per `key` valori di un insieme limitato, come tipi di evento o nomi di processi.


## Related topics

- [Argomenti avanzati](https://kawax.biz/it/advanced/index.md)
- [Driver di sessione personalizzati nei pacchetti](https://kawax.biz/it/advanced/package-session-drivers.md)
- [Store di cache personalizzati e contratti nei pacchetti](https://kawax.biz/it/advanced/package-cache-drivers.md)
- [Laravel Pulse](https://kawax.biz/it/pulse.md)
- [UserProvider personalizzati nei pacchetti](https://kawax.biz/it/advanced/package-user-providers.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.