Esta guía se basa en el código fuente de Pulse 1.11.0. El evento
ReportGenerated de los ejemplos es una clase hipotética con fines ilustrativos. En un paquete real, sustitúyelo por tu propio evento.Cómo funciona
Cuando un recorder recibe un evento, añade registros al búfer de Pulse. El búfer se guarda por lotes en el momento de la ingesta.Crear un recorder
Un recorder declara los eventos a los que se suscribe en la propiedadlisten e implementa el trabajo en el método record(). El siguiente ejemplo registra el evento ReportGenerated que despacha un paquete. Se supone que el evento tiene las propiedades $type y $durationMs.
Ignores y Sampling leen la configuración ignore y sample_rate descrita más abajo.
Registrar el recorder en la aplicación
Registra el recorder en el arrayrecorders del archivo config/pulse.php de la aplicación. Usa el nombre de la clase del recorder como clave y especifica como valor el indicador de activación y la configuración.
PulseServiceProvider carga pulse.recorders y registra los recorders cuando pulse.enabled está activado. Un recorder con enabled en false no se registra. En lugar de reescribir esta configuración automáticamente desde el paquete, es más seguro mostrar el ejemplo de configuración en las instrucciones de instalación.
Tipos de agregación
Pulse::record() devuelve un Entry. Al encadenar count(), min(), max(), sum() o avg(), se guarda el agregado correspondiente en pulse_aggregates.
min(), max(), sum() y avg() usan value en su cálculo. count() por sí solo no necesita value.
Cuando un evento se dispara con mucha frecuencia, onlyBuckets() reduce el número de filas en pulse_entries.
Guardar un valor de cadena
Cuando quieras guardar una cadena, como el estado más reciente, en lugar de agregar un número, usaPulse::set(). El valor se guarda en la tabla pulse_values.
value debe pasarse como string.
Aplazar el trabajo costoso
El closure que se pasa aPulse::lazy() no se ejecuta de inmediato. Se ejecuta cuando Pulse ingiere los datos. Úsalo cuando el registro lleve tiempo y quieras que se ejecute después de enviar la respuesta.
Registrar el usuario autenticado
Cuando necesites el identificador del usuario autenticado, usaPulse::resolveAuthenticatedUserId(). Devuelve null cuando no hay ningún usuario autenticado.
Ignorar, muestrear y filtrar
Usa estas cuatro herramientas para reducir lo que se registra:- Configuración
ignore: omite el registro cuando el valor pasado ashouldIgnore()coincide con alguna de las expresiones regulares. En el ejemplo anterior, se omiten los eventos cuyo$event->typecoincide con/^debug_/. - Configuración
sample_rate: la compruebashouldSample().1registra todos los eventos y0.1registra aproximadamente el 10 %. Pulse::ignore(): desactiva el registro dentro del callback y devuelve el resultado del callback.Pulse::filter(): recibe cadaEntryoValueantes de guardarlo y solo guarda los elementos para los que devuelvetrue.
Manejo de excepciones
Pulse envuelve el trabajo de los recorders y la ingesta enrescue(). Las excepciones lanzadas dentro de un recorder no llegan a tu aplicación. Si handleExceptionsUsing() no está configurado, la excepción se descarta silenciosamente. Para reportar excepciones, configúralo en tu aplicación.
Pruebas
Para probar un recorder, puedes despachar el evento, llamar aPulse::ingest() y comprobar la fila guardada. El siguiente ejemplo se ha derivado del código fuente de Pulse y no se ha ejecutado. Asegúrate de que pulse.enabled esté activado en tu entorno de pruebas.
Diseño de las claves
key es la unidad de agregación. Si usas valores que crecen sin límite, como IDs de usuario o URLs, el volumen de datos aumenta y los agregados se vuelven difíciles de leer. Usa para key valores de un conjunto limitado, como tipos de evento o nombres de procesos.