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

# Recorders Pulse personnalisés dans les packages

> Découvrez comment utiliser les recorders de Laravel Pulse pour agréger sur le tableau de bord les événements propres à un package. Abonnement avec listen, agrégation avec Pulse::record, réglages ignore et sample_rate, et gestion des exceptions.

Laravel Pulse agrège sur le tableau de bord les requêtes, les requêtes SQL, les jobs et plus encore. Lorsque votre package effectue son propre travail, un recorder personnalisé vous permet de surveiller dans Pulse le nombre et la durée de ce travail.

Ce guide construit un recorder qui s'abonne à un événement déclenché par un package et enregistre son nombre et sa durée. Pour l'utilisation de base de Pulse, consultez [Pulse](https://kawax.biz/fr/pulse.md).

> [!NOTE]
>
> Ce guide s'appuie sur le code source de Pulse 1.11.0. L'événement `ReportGenerated` des exemples est une classe hypothétique utilisée à titre d'illustration. Dans un vrai package, remplacez-le par votre propre événement.

## Fonctionnement

Lorsqu'un recorder reçoit un événement, il ajoute des enregistrements au tampon de Pulse. Le tampon est sauvegardé par lots au moment de l'ingestion.

```mermaid theme={null}
flowchart LR
    A["Événement déclenché"] --> B["listen appelle<br>record"]
    B --> C["Pulse::record<br>crée une Entry"]
    C --> D["Tampon Pulse"]
    D --> E["Sauvegardé à l'ingestion"]
    E --> F["pulse_entries"]
    E --> G["pulse_aggregates"]
    F --> H["Affiché sur le tableau de bord"]
    G --> H
```

## Créer un recorder

Un recorder déclare les événements auxquels il s'abonne dans la propriété `listen` et implémente le traitement dans la méthode `record()`. L'exemple ci-dessous enregistre l'événement `ReportGenerated` déclenché par un package. On suppose que l'événement possède les propriétés `$type` et `$durationMs`.

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

Les traits `Ignores` et `Sampling` lisent les réglages `ignore` et `sample_rate` décrits plus bas.

## Enregistrer le recorder dans l'application

Enregistrez le recorder dans le tableau `recorders` du fichier `config/pulse.php` de l'application. Utilisez le nom de classe du recorder comme clé et indiquez comme valeur l'indicateur d'activation et les réglages.

```php theme={null}
'recorders' => [
    // Conservez les recorders existants tels quels
    Acme\Reports\Pulse\ReportGenerationRecorder::class => [
        'enabled' => true,
        'sample_rate' => 1,
        'ignore' => ['/^debug_/'],
    ],
],
```

`PulseServiceProvider` charge `pulse.recorders` et enregistre les recorders lorsque `pulse.enabled` est activé. Un recorder dont `enabled` vaut `false` n'est pas enregistré. Plutôt que de réécrire ce réglage automatiquement depuis le package, il est plus sûr de présenter l'exemple de configuration dans les instructions d'installation.

## Types d'agrégation

`Pulse::record()` renvoie une `Entry`. En chaînant `count()`, `min()`, `max()`, `sum()` ou `avg()`, l'agrégat correspondant est stocké dans `pulse_aggregates`.

| Méthode | Valeur stockée |
| - | - |
| `count()` | Nombre |
| `min()` | Valeur minimale |
| `max()` | Valeur maximale |
| `sum()` | Somme |
| `avg()` | Moyenne |
| `onlyBuckets()` | Ne stocke que les résultats agrégés, sans enregistrements individuels dans `pulse_entries` |

`min()`, `max()`, `sum()` et `avg()` utilisent `value` dans leur calcul. `count()` seul n'a pas besoin de `value`.

Lorsqu'un événement se déclenche très fréquemment, `onlyBuckets()` réduit le nombre de lignes dans `pulse_entries`.

## Stocker une valeur de type chaîne

Lorsque vous voulez stocker une chaîne, comme le dernier état, plutôt qu'agréger un nombre, utilisez `Pulse::set()`. La valeur est enregistrée dans la table `pulse_values`.

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

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

Le `value` doit être passé sous forme de `string`.

## Différer les traitements coûteux

La closure passée à `Pulse::lazy()` ne s'exécute pas immédiatement. Elle s'exécute lorsque Pulse ingère les données. Utilisez-la lorsque l'enregistrement prend du temps et que vous voulez qu'il s'exécute après l'envoi de la réponse.

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

## Enregistrer l'utilisateur authentifié

Lorsque vous avez besoin de l'identifiant de l'utilisateur authentifié, utilisez `Pulse::resolveAuthenticatedUserId()`. Elle renvoie `null` lorsqu'aucun utilisateur n'est authentifié.

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

## Ignorer, échantillonner et filtrer

Utilisez ces quatre outils pour réduire ce qui est enregistré :

* Réglage `ignore` : ignore l'enregistrement lorsque la valeur passée à `shouldIgnore()` correspond à l'une des expressions régulières. Dans l'exemple ci-dessus, les événements dont `$event->type` correspond à `/^debug_/` sont ignorés.
* Réglage `sample_rate` : vérifié par `shouldSample()`. `1` enregistre tous les événements et `0.1` en enregistre environ 10 %.
* `Pulse::ignore()` : désactive l'enregistrement dans le callback et renvoie le résultat du callback.
* `Pulse::filter()` : reçoit chaque `Entry` ou `Value` avant son stockage et n'enregistre que les éléments pour lesquels il renvoie `true`.

## Gestion des exceptions

Pulse encapsule le travail des recorders et l'ingestion dans `rescue()`. Les exceptions levées dans un recorder n'atteignent pas votre application. Si `handleExceptionsUsing()` n'est pas défini, l'exception est ignorée silencieusement. Pour signaler les exceptions, configurez-le dans votre application.

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

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

## Tests

Pour tester un recorder, vous pouvez déclencher l'événement, appeler `Pulse::ingest()` et vérifier la ligne enregistrée. L'exemple ci-dessous est dérivé du code source de Pulse et n'a pas été exécuté. Assurez-vous que `pulse.enabled` est activé dans votre environnement de test.

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

## Concevoir les clés

`key` est l'unité d'agrégation. Si vous utilisez des valeurs qui croissent sans limite, comme des ID d'utilisateur ou des URL, le volume de données augmente et les agrégats deviennent difficiles à lire. Utilisez pour `key` des valeurs issues d'un ensemble limité, comme des types d'événements ou des noms de processus.


## Related topics

- [Sujets avancés](https://kawax.biz/fr/advanced/index.md)
- [Laravel Pulse](https://kawax.biz/fr/pulse.md)
- [UserProvider personnalisé dans un package](https://kawax.biz/fr/advanced/package-user-providers.md)
- [Drivers de session personnalisés pour les packages](https://kawax.biz/fr/advanced/package-session-drivers.md)
- [Stores de cache personnalisés et contrats pour les packages](https://kawax.biz/fr/advanced/package-cache-drivers.md)


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