Vai al contenuto principale
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.
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.

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

Registrare l’utente autenticato

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

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.

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.

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.
Ultima modifica il 18 novembre 2026