Passer au contenu principal
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.
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.

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.
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.
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. 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.
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.

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é.

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.

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.

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.
Dernière modification le 18 novembre 2026