Saltar al contenido principal
Laravel Pulse agrega en el panel las solicitudes, consultas, jobs y más. Cuando tu paquete realiza su propio trabajo, un recorder personalizado te permite monitorizar en Pulse el número y la duración de ese trabajo. Esta guía construye un recorder que se suscribe a un evento que despacha un paquete y registra su número y duración. Para el uso básico de Pulse, consulta Pulse.
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 propiedad listen 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.
Los traits 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 array recorders 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, usa Pulse::set(). El valor se guarda en la tabla pulse_values.
El value debe pasarse como string.

Aplazar el trabajo costoso

El closure que se pasa a Pulse::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, usa Pulse::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 a shouldIgnore() coincide con alguna de las expresiones regulares. En el ejemplo anterior, se omiten los eventos cuyo $event->type coincide con /^debug_/.
  • Configuración sample_rate: la comprueba shouldSample(). 1 registra todos los eventos y 0.1 registra aproximadamente el 10 %.
  • Pulse::ignore(): desactiva el registro dentro del callback y devuelve el resultado del callback.
  • Pulse::filter(): recibe cada Entry o Value antes de guardarlo y solo guarda los elementos para los que devuelve true.

Manejo de excepciones

Pulse envuelve el trabajo de los recorders y la ingesta en rescue(). 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 a Pulse::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.
Última modificación el 18 de noviembre de 2026