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.
Ignores e Sampling leggono le impostazioni ignore e sample_rate descritte più avanti.
Registrare il recorder nell’applicazione
Registra il recorder nell’arrayrecorders 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, usaPulse::set(). Il valore viene salvato nella tabella pulse_values.
value deve essere passato come string.
Rimandare il lavoro oneroso
La closure passata aPulse::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, usaPulse::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 ashouldIgnore()corrisponde a una delle espressioni regolari. Nell’esempio sopra, vengono saltati gli eventi il cui$event->typecorrisponde a/^debug_/. - Impostazione
sample_rate: verificata dashouldSample().1registra ogni evento e0.1circa il 10%. Pulse::ignore(): disattiva la registrazione all’interno della callback e restituisce il risultato della callback.Pulse::filter(): riceve ogniEntryoValueprima del salvataggio e salva solo gli elementi per cui restituiscetrue.
Gestione delle eccezioni
Pulse racchiude il lavoro dei recorder e l’ingest inrescue(). 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, chiamarePulse::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.