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

# Eigene Pulse-Recorder in Paketen

> Erfahren Sie, wie Sie mit Recordern von Laravel Pulse paketeigene Ereignisse im Dashboard aggregieren. Behandelt werden das Abonnieren mit listen, das Aggregieren mit Pulse::record, die Einstellungen ignore und sample_rate sowie die Behandlung von Exceptions.

Laravel Pulse aggregiert Requests, Queries, Jobs und mehr im Dashboard. Wenn Ihr Paket eigene Arbeit erledigt, können Sie mit einem eigenen Recorder die Anzahl und Dauer dieser Arbeit in Pulse überwachen.

Dieser Leitfaden baut einen Recorder, der ein von einem Paket ausgelöstes Event abonniert und dessen Anzahl und Dauer aufzeichnet. Die grundlegende Verwendung von Pulse finden Sie unter [Pulse](https://kawax.biz/de/pulse.md).

> [!NOTE]
>
> Dieser Leitfaden basiert auf dem Quellcode von Pulse 1.11.0. Das Event `ReportGenerated` in den Beispielen ist eine hypothetische Klasse zur Veranschaulichung. Ersetzen Sie es in einem echten Paket durch Ihr eigenes Event.

## Funktionsweise

Wenn ein Recorder ein Event empfängt, legt er Datensätze im Puffer von Pulse ab. Der Puffer wird beim Ingest gesammelt gespeichert.

```mermaid theme={null}
flowchart LR
    A["Event ausgelöst"] --> B["listen ruft<br>record auf"]
    B --> C["Pulse::record<br>erzeugt einen Entry"]
    C --> D["Pulse-Puffer"]
    D --> E["Beim Ingest gespeichert"]
    E --> F["pulse_entries"]
    E --> G["pulse_aggregates"]
    F --> H["Im Dashboard angezeigt"]
    G --> H
```

## Einen Recorder erstellen

Ein Recorder deklariert die zu abonnierenden Events in der Property `listen` und implementiert die Verarbeitung in der Methode `record()`. Das folgende Beispiel zeichnet das Event `ReportGenerated` auf, das ein Paket auslöst. Es wird angenommen, dass das Event die Properties `$type` und `$durationMs` besitzt.

```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();
    }
}
```

Die Traits `Ignores` und `Sampling` lesen die weiter unten beschriebenen Einstellungen `ignore` und `sample_rate`.

## Den Recorder in der Anwendung registrieren

Registrieren Sie den Recorder im Array `recorders` der Datei `config/pulse.php` der Anwendung. Verwenden Sie den Klassennamen des Recorders als Schlüssel und geben Sie als Wert das Aktivierungsflag und die Einstellungen an.

```php theme={null}
'recorders' => [
    // Bestehende Recorder unverändert lassen
    Acme\Reports\Pulse\ReportGenerationRecorder::class => [
        'enabled' => true,
        'sample_rate' => 1,
        'ignore' => ['/^debug_/'],
    ],
],
```

`PulseServiceProvider` lädt `pulse.recorders` und registriert die Recorder, wenn `pulse.enabled` aktiviert ist. Ein Recorder mit `enabled` auf `false` wird nicht registriert. Statt diese Einstellung automatisch aus dem Paket heraus umzuschreiben, ist es sicherer, das Konfigurationsbeispiel in der Installationsanleitung zu zeigen.

## Aggregationsarten

`Pulse::record()` gibt einen `Entry` zurück. Wenn Sie `count()`, `min()`, `max()`, `sum()` oder `avg()` verketten, wird das entsprechende Aggregat in `pulse_aggregates` gespeichert.

| Methode | Gespeicherter Wert |
| - | - |
| `count()` | Anzahl |
| `min()` | Minimalwert |
| `max()` | Maximalwert |
| `sum()` | Summe |
| `avg()` | Durchschnitt |
| `onlyBuckets()` | Speichert nur die Aggregationsergebnisse, ohne einzelne Datensätze in `pulse_entries` |

`min()`, `max()`, `sum()` und `avg()` verwenden `value` für die Berechnung. `count()` allein benötigt keinen `value`.

Wenn ein Event sehr häufig ausgelöst wird, reduziert `onlyBuckets()` die Anzahl der Zeilen in `pulse_entries`.

## Einen String-Wert speichern

Wenn Sie statt einer Zahl zum Aggregieren einen String wie den aktuellen Zustand speichern möchten, verwenden Sie `Pulse::set()`. Der Wert wird in der Tabelle `pulse_values` gespeichert.

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

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

Der `value` muss als `string` übergeben werden.

## Aufwendige Arbeit verzögern

Die an `Pulse::lazy()` übergebene Closure wird nicht sofort ausgeführt. Sie läuft, wenn Pulse die Daten einliest. Verwenden Sie sie, wenn das Aufzeichnen Zeit kostet und erst nach dem Senden der Response laufen soll.

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

## Den authentifizierten Benutzer aufzeichnen

Wenn Sie die Kennung des authentifizierten Benutzers benötigen, verwenden Sie `Pulse::resolveAuthenticatedUserId()`. Ist kein Benutzer authentifiziert, wird `null` zurückgegeben.

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

## Ignorieren, Sampling und Filtern

Mit diesen vier Werkzeugen reduzieren Sie, was aufgezeichnet wird:

* Einstellung `ignore`: Überspringt das Aufzeichnen, wenn der an `shouldIgnore()` übergebene Wert auf einen der regulären Ausdrücke passt. Im obigen Beispiel werden Events übersprungen, deren `$event->type` auf `/^debug_/` passt.
* Einstellung `sample_rate`: Wird von `shouldSample()` geprüft. `1` zeichnet jedes Event auf, `0.1` etwa 10 %.
* `Pulse::ignore()`: Deaktiviert das Aufzeichnen innerhalb des Callbacks und gibt das Ergebnis des Callbacks zurück.
* `Pulse::filter()`: Erhält jeden `Entry` oder `Value` vor dem Speichern und speichert nur die Einträge, für die es `true` zurückgibt.

## Behandlung von Exceptions

Pulse umschließt die Arbeit der Recorder und das Ingest mit `rescue()`. Exceptions, die in einem Recorder geworfen werden, erreichen Ihre Anwendung nicht. Ist `handleExceptionsUsing()` nicht gesetzt, wird die Exception stillschweigend verworfen. Um Exceptions zu melden, konfigurieren Sie dies in Ihrer Anwendung.

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

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

## Testen

Um einen Recorder zu testen, können Sie das Event auslösen, `Pulse::ingest()` aufrufen und die gespeicherte Zeile prüfen. Das folgende Beispiel ist aus dem Quellcode von Pulse abgeleitet und wurde nicht ausgeführt. Stellen Sie sicher, dass `pulse.enabled` in Ihrer Testumgebung aktiviert ist.

```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,
    ]);
});
```

## Schlüssel entwerfen

`key` ist die Einheit der Aggregation. Wenn Sie unbegrenzt wachsende Werte wie Benutzer-IDs oder URLs verwenden, wächst die Datenmenge und die Aggregate werden schwer lesbar. Verwenden Sie für `key` Werte aus einer begrenzten Menge, etwa Event-Typen oder Prozessnamen.


## Related topics

- [Weiterführende Themen](https://kawax.biz/de/advanced/index.md)
- [Laravel Pulse](https://kawax.biz/de/pulse.md)
- [Eigene Session-Treiber in Paketen](https://kawax.biz/de/advanced/package-session-drivers.md)
- [Eigene UserProvider in Paketen](https://kawax.biz/de/advanced/package-user-providers.md)
- [Eigene Cache-Stores und Verträge in Paketen](https://kawax.biz/de/advanced/package-cache-drivers.md)


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