Skip to main content
Laravel Pulse aggregates requests, queries, jobs and more on the dashboard. When your package does its own work, a custom recorder lets you monitor the count and duration of that work in Pulse. This guide builds a recorder that subscribes to an event dispatched by a package and records its count and duration. For basic Pulse usage, see Pulse.
This guide is based on the source code of Pulse 1.11.0. The ReportGenerated event in the examples is a hypothetical class for illustration. In a real package, replace it with your own event.

How It Works

When a recorder receives an event, it adds records to Pulse’s buffer. The buffer is saved in batches at ingest time.

Create a Recorder

A recorder declares the events to subscribe to in the listen property and implements the work in the record() method. The example below records the ReportGenerated event that a package dispatches. The event is assumed to have $type and $durationMs properties.
The Ignores and Sampling traits read the ignore and sample_rate settings described below.

Register the Recorder in the Application

Register the recorder in the recorders array of the application’s config/pulse.php. Use the recorder’s class name as the key, and specify the enable flag and settings as the value.
PulseServiceProvider loads pulse.recorders and registers the recorders when pulse.enabled is on. A recorder with enabled set to false is not registered. Rather than rewriting this setting automatically from the package, it is safer to show the configuration example in the installation instructions.

Aggregate Types

Pulse::record() returns an Entry. Chaining count(), min(), max(), sum() or avg() stores the matching aggregate in pulse_aggregates. min(), max(), sum() and avg() use value in their calculation. count() alone does not need a value. When an event fires very frequently, onlyBuckets() reduces the number of rows in pulse_entries.

Store a String Value

When you want to store a string, such as the latest state, rather than aggregate a number, use Pulse::set(). The value is saved in the pulse_values table.
The value must be passed as a string.

Defer Expensive Work

The closure passed to Pulse::lazy() does not run immediately. It runs when Pulse ingests the data. Use it when recording takes time and you want it to run after the response is sent.

Record the Authenticated User

When you need the identifier of the authenticated user, use Pulse::resolveAuthenticatedUserId(). It returns null when no user is authenticated.

Ignore, Sample and Filter

Use these four tools to reduce what gets recorded:
  • ignore setting: Skips recording when the value passed to shouldIgnore() matches one of the regular expressions. In the example above, events whose $event->type matches /^debug_/ are skipped.
  • sample_rate setting: Checked by shouldSample(). 1 records every event, and 0.1 records about 10%.
  • Pulse::ignore(): Disables recording inside the callback and returns the callback’s result.
  • Pulse::filter(): Receives each Entry or Value before it is stored and saves only the items for which it returns true.

Exception Handling

Pulse wraps recorder work and ingestion in rescue(). Exceptions thrown inside a recorder do not reach your application. If handleExceptionsUsing() is not set, the exception is silently discarded. To report exceptions, configure this in your application.

Testing

To test a recorder, you can dispatch the event, call Pulse::ingest(), and check the saved row. The example below is derived from the Pulse source and has not been run. Make sure pulse.enabled is on in your test environment.

Designing Keys

key is the unit of aggregation. If you use values that grow without limit, such as user IDs or URLs, the data volume grows and the aggregates become hard to read. Use values with a limited set, such as event types or process names, for key.
Last modified on November 18, 2026