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 thelisten 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.
Ignores and Sampling traits read the ignore and sample_rate settings described below.
Register the Recorder in the Application
Register the recorder in therecorders 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, usePulse::set(). The value is saved in the pulse_values table.
value must be passed as a string.
Defer Expensive Work
The closure passed toPulse::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, usePulse::resolveAuthenticatedUserId(). It returns null when no user is authenticated.
Ignore, Sample and Filter
Use these four tools to reduce what gets recorded:ignoresetting: Skips recording when the value passed toshouldIgnore()matches one of the regular expressions. In the example above, events whose$event->typematches/^debug_/are skipped.sample_ratesetting: Checked byshouldSample().1records every event, and0.1records about 10%.Pulse::ignore(): Disables recording inside the callback and returns the callback’s result.Pulse::filter(): Receives eachEntryorValuebefore it is stored and saves only the items for which it returnstrue.
Exception Handling
Pulse wraps recorder work and ingestion inrescue(). 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, callPulse::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.