> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Eigen Pulse-recorders in packages

> Leer hoe je met recorders van Laravel Pulse package-specifieke events op het dashboard aggregeert. Behandelt abonneren met listen, aggregeren met Pulse::record, de instellingen ignore en sample_rate, en het afhandelen van exceptions.

Laravel Pulse aggregeert requests, queries, jobs en meer op het dashboard. Wanneer je package eigen werk uitvoert, kun je met een eigen recorder het aantal en de duur van dat werk in Pulse monitoren.

Deze gids bouwt een recorder die zich abonneert op een event dat een package dispatcht en het aantal en de duur ervan vastlegt. Zie [Pulse](https://kawax.biz/nl/pulse.md) voor het basisgebruik van Pulse.

> [!NOTE]
>
> Deze gids is gebaseerd op de broncode van Pulse 1.11.0. Het event `ReportGenerated` in de voorbeelden is een hypothetische klasse ter illustratie. Vervang het in een echt package door je eigen event.

## Hoe het werkt

Wanneer een recorder een event ontvangt, voegt hij records toe aan de buffer van Pulse. De buffer wordt bij de ingest in één keer opgeslagen.

```mermaid theme={null}
flowchart LR
    A["Event gedispatcht"] --> B["listen roept<br>record aan"]
    B --> C["Pulse::record<br>maakt een Entry"]
    C --> D["Pulse-buffer"]
    D --> E["Opgeslagen bij ingest"]
    E --> F["pulse_entries"]
    E --> G["pulse_aggregates"]
    F --> H["Getoond op dashboard"]
    G --> H
```

## Een recorder maken

Een recorder declareert de events waarop hij zich abonneert in de property `listen` en implementeert het werk in de methode `record()`. Het voorbeeld hieronder legt het event `ReportGenerated` vast dat een package dispatcht. We gaan ervan uit dat het event de properties `$type` en `$durationMs` heeft.

```php theme={null}
<?php

namespace Acme\Reports\Pulse;

use Acme\Reports\Events\ReportGenerated;
use Laravel\Pulse\Facades\Pulse;
use Laravel\Pulse\Recorders\Concerns\Ignores;
use Laravel\Pulse\Recorders\Concerns\Sampling;

class ReportGenerationRecorder
{
    use Ignores, Sampling;

    public array $listen = [
        ReportGenerated::class,
    ];

    public function record(ReportGenerated $event): void
    {
        if ($this->shouldIgnore($event->type) || ! $this->shouldSample()) {
            return;
        }

        Pulse::record(
            type: 'report_generation',
            key: $event->type,
            value: $event->durationMs,
        )->count()->avg()->max();
    }
}
```

De traits `Ignores` en `Sampling` lezen de hieronder beschreven instellingen `ignore` en `sample_rate`.

## De recorder in de applicatie registreren

Registreer de recorder in de array `recorders` van `config/pulse.php` in de applicatie. Gebruik de klassenaam van de recorder als sleutel en geef als waarde de activeringsvlag en de instellingen op.

```php theme={null}
'recorders' => [
    // Laat bestaande recorders ongewijzigd
    Acme\Reports\Pulse\ReportGenerationRecorder::class => [
        'enabled' => true,
        'sample_rate' => 1,
        'ignore' => ['/^debug_/'],
    ],
],
```

`PulseServiceProvider` laadt `pulse.recorders` en registreert de recorders wanneer `pulse.enabled` aan staat. Een recorder met `enabled` op `false` wordt niet geregistreerd. In plaats van deze instelling automatisch vanuit het package te herschrijven, is het veiliger om het configuratievoorbeeld in de installatie-instructies te tonen.

## Soorten aggregaties

`Pulse::record()` geeft een `Entry` terug. Door `count()`, `min()`, `max()`, `sum()` of `avg()` te chainen wordt het bijbehorende aggregaat in `pulse_aggregates` opgeslagen.

| Methode | Opgeslagen waarde |
| - | - |
| `count()` | Aantal |
| `min()` | Minimumwaarde |
| `max()` | Maximumwaarde |
| `sum()` | Som |
| `avg()` | Gemiddelde |
| `onlyBuckets()` | Slaat alleen de geaggregeerde resultaten op, zonder individuele records in `pulse_entries` |

`min()`, `max()`, `sum()` en `avg()` gebruiken `value` in hun berekening. `count()` alleen heeft geen `value` nodig.

Wanneer een event heel vaak optreedt, vermindert `onlyBuckets()` het aantal rijen in `pulse_entries`.

## Een stringwaarde opslaan

Wanneer je een string wilt opslaan, zoals de laatste status, in plaats van een getal te aggregeren, gebruik je `Pulse::set()`. De waarde wordt opgeslagen in de tabel `pulse_values`.

```php theme={null}
use Laravel\Pulse\Facades\Pulse;

Pulse::set('report_status', $event->type, $event->status);
```

De `value` moet als `string` worden meegegeven.

## Zwaar werk uitstellen

De closure die je aan `Pulse::lazy()` meegeeft, wordt niet direct uitgevoerd. Hij draait wanneer Pulse de data inleest. Gebruik dit wanneer het vastleggen tijd kost en je het na het versturen van de response wilt uitvoeren.

```php theme={null}
Pulse::lazy(function () use ($event) {
    Pulse::record('report_size', $event->type, $event->rows)->sum();
});
```

## De geauthenticeerde gebruiker vastleggen

Wanneer je de identifier van de geauthenticeerde gebruiker nodig hebt, gebruik je `Pulse::resolveAuthenticatedUserId()`. Deze geeft `null` terug wanneer er geen gebruiker is geauthenticeerd.

```php theme={null}
$userId = Pulse::resolveAuthenticatedUserId();
```

## Negeren, samplen en filteren

Gebruik deze vier hulpmiddelen om te beperken wat er wordt vastgelegd:

* Instelling `ignore`: slaat het vastleggen over wanneer de waarde die aan `shouldIgnore()` wordt meegegeven overeenkomt met een van de reguliere expressies. In het voorbeeld hierboven worden events overgeslagen waarvan `$event->type` overeenkomt met `/^debug_/`.
* Instelling `sample_rate`: wordt gecontroleerd door `shouldSample()`. `1` legt elk event vast en `0.1` ongeveer 10%.
* `Pulse::ignore()`: schakelt het vastleggen binnen de callback uit en geeft het resultaat van de callback terug.
* `Pulse::filter()`: ontvangt elke `Entry` of `Value` vóór het opslaan en slaat alleen de items op waarvoor het `true` teruggeeft.

## Exceptions afhandelen

Pulse verpakt het werk van recorders en de ingest in `rescue()`. Exceptions die in een recorder worden gegooid, bereiken je applicatie niet. Als `handleExceptionsUsing()` niet is ingesteld, wordt de exception stilzwijgend weggegooid. Configureer dit in je applicatie om exceptions te rapporteren.

```php theme={null}
use Laravel\Pulse\Facades\Pulse;

Pulse::handleExceptionsUsing(fn (Throwable $e) => report($e));
```

## Testen

Om een recorder te testen, kun je het event dispatchen, `Pulse::ingest()` aanroepen en de opgeslagen rij controleren. Het voorbeeld hieronder is afgeleid van de broncode van Pulse en is niet uitgevoerd. Zorg ervoor dat `pulse.enabled` aan staat in je testomgeving.

```php theme={null}
use Acme\Reports\Events\ReportGenerated;
use Laravel\Pulse\Facades\Pulse;

it('records ReportGenerated in pulse_entries', function () {
    event(new ReportGenerated(type: 'monthly', durationMs: 120));

    Pulse::ingest();

    $this->assertDatabaseHas('pulse_entries', [
        'type' => 'report_generation',
        'key' => 'monthly',
        'value' => 120,
    ]);
});
```

## Sleutels ontwerpen

`key` is de eenheid van aggregatie. Als je waarden gebruikt die onbeperkt groeien, zoals gebruikers-ID's of URL's, groeit de hoeveelheid data en worden de aggregaten moeilijk leesbaar. Gebruik voor `key` waarden uit een beperkte set, zoals eventtypes of procesnamen.


## Related topics

- [Geavanceerde onderwerpen](https://kawax.biz/nl/advanced/index.md)
- [Laravel Pulse](https://kawax.biz/nl/pulse.md)
- [Eigen sessiedrivers voor packages](https://kawax.biz/nl/advanced/package-session-drivers.md)
- [Core-package en eigen drivers - Feedable](https://kawax.biz/nl/packages/feedable/core.md)
- [Eigen cachestores en contracten voor packages](https://kawax.biz/nl/advanced/package-cache-drivers.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.