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.
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 tableaurecorders 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, utilisezPulse::set(). La valeur est enregistrée dans la table pulse_values.
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é, utilisezPulse::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->typecorrespond à/^debug_/sont ignorés. - Réglage
sample_rate: vérifié parshouldSample().1enregistre tous les événements et0.1en enregistre environ 10 %. Pulse::ignore(): désactive l’enregistrement dans le callback et renvoie le résultat du callback.Pulse::filter(): reçoit chaqueEntryouValueavant son stockage et n’enregistre que les éléments pour lesquels il renvoietrue.
Gestion des exceptions
Pulse encapsule le travail des recorders et l’ingestion dansrescue(). 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, appelerPulse::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.