Les event formatters sont des classes d’assistance permettant de formater les métadonnées d’événements pour les transactions AppSignal. Dans la gem AppSignal, les event formatters sont utilisés pour formater les métadonnées d’événements provenant des événements d’instrumentation ActiveSupport::Notifications vers des métadonnées d’événements AppSignal.
Lorsqu’un bloc de code est instrumenté par ActiveSupport::Notifications, AppSignal enregistrera l’événement sur les transactions, comme il le ferait pour l’assistant Appsignal.instrument. Les event formatters permettent aux données transmises à l’appel de la méthode ActiveSupport::Notifications.instrument d’être formatées pour les événements AppSignal.
Les métadonnées des événements formatés par les event formatters seront visibles sur les pages de détails des incidents de performance dans la chronologie des événements. Survolez un événement spécifique et la fenêtre contextuelle de survol affichera des détails comme la base de données exacte interrogée ou la requête qui a été exécutée.
Remarque : s’il n’y a pas d’autres raisons d’utiliser l’instrumentation
ActiveSupport::Notifications que pour
l’instrumentation AppSignal, nous recommandons d’utiliser l’assistant
Appsignal.instrument pour l’instrumentation.
L’utilisation de ActiveSupport::Notifications ajoute plus de surcharge que
l’appel direct à AppSignal.instrument. Aucun event formatter ne sera
nécessaire non plus, car AppSignal.instrument accepte les métadonnées à
définir directement. format. Cette méthode format reçoit le Hash de payload de l’événement et doit renvoyer un Array de trois valeurs.
Il est possible d’ajouter un event formatter pour les bibliothèques qui utilisent l’instrumentation ActiveSupport::Notifications, mais veillez à ce qu’il n’y ait pas déjà un event formatter enregistré pour cela.
Il est également possible de créer un event formatter pour vos propres événements. Lorsque vous ajoutez vos propres noms d’événements, veuillez tenir compte des directives sur le nommage des événements.
Chaque event formatter reçoit un Hash de « payload » de métadonnées d’événement à partir duquel l’event formatter peut formater les métadonnées de l’événement dans AppSignal. Ces métadonnées d’événement AppSignal doivent être renvoyées par l’event formatter dans cet ordre dans un Array :
def format(payload)
[
"event title",
"event body",
Appsignal::EventFormatter::DEFAULT
]
end
- Un titre d’événement (
String)
- Un titre plus descriptif d’un événement, tel que
"Fetch current user" ou "Fetch blog post comments". Il apparaîtra à côté du nom de l’événement dans l’arbre des événements sur la page d’échantillon de performance pour fournir un peu plus de contexte sur ce qui se passe.
- Un corps d’événement (
String)
- Plus de détails tels que la requête de base de données qui a été utilisée par l’événement.
- Un format de corps d’événement (
Integer)
- Le format du corps prend en charge des formateurs pour nettoyer les données fournies dans l’argument
body afin de supprimer toute donnée sensible de la valeur. Il existe actuellement deux valeurs prises en charge pour l’argument body_format.
Appsignal::EventFormatter::DEFAULT
- Cette valeur par défaut indique à AppSignal de laisser la valeur intacte et de ne pas nettoyer les données.
Appsignal::EventFormatter::SQL_BODY_FORMAT
- La valeur
SQL_BODY_FORMAT indique à AppSignal d’exécuter vos données via le sanitizer SQL et de nettoyer toutes les valeurs des requêtes SQL.
-- An event body with the value of:
SELECT * FROM users WHERE email = 'hector@appsignal.com' AND password = 'iamabot'
-- becomes
SELECT * FROM users WHERE email = ? AND password = ?
Avertissement : l’event formatter n’a aucune gestion d’exception qui
l’entoure. Si l’event formatter personnalisé lève une erreur, il fera planter
la requête web ou la tâche en arrière-plan.
# A custom event formatter class
class MyCustomEventFormatter
def format(payload)
[
payload[:title],
payload[:body],
Appsignal::EventFormatter::DEFAULT
]
end
end
# Register the custom event formatter class for a specific event
Appsignal::EventFormatter.register("event.custom", MyCustomEventFormatter)
# Can be registerd multiple times for other event names
Appsignal::EventFormatter.register("other_event.custom", MyCustomEventFormatter)
ActiveSupport::Notifications.instrument(
"event.custom", # Use the registered event name
{ # Pass along event metadata
:title => "some event name",
:body => "some event body"
}
) do
sleep 2
end
Changements dans la gem 2.5
Dans la version 2.5.2 de la gem Ruby AppSignal, des modifications ont été apportées à la façon dont les event formatters sont enregistrés. L’ancienne méthode d’enregistrement des event formatters a été dépréciée dans cette version et sera supprimée dans la version 3.0 de la gem Ruby.
La nouvelle méthode d’enregistrement des EventFormatters permettra aux formateurs personnalisés d’être enregistrés après le chargement d’AppSignal. Cela permet aux EventFormatters d’être enregistrés dans des initializers Rails.
Dans la version 2.5.1 et antérieures de la gem, il est possible d’enregistrer un event formatter comme dans l’exemple suivant, en appelant la méthode register dans la classe elle-même.
# Pre 2.5.2 method of registering event formatters
# This method is now deprecated
class MyCustomEventFormatter < Appsignal::EventFormatter
register "event.custom"
def format(payload)
[payload[:title], payload[:body], Appsignal::EventFormatter::DEFAULT]
end
end
class MyCustomEventFormatter
def format(payload)
[payload[:title], payload[:body], Appsignal::EventFormatter::DEFAULT]
end
end
Appsignal::EventFormatter.register("event.custom", MyCustomEventFormatter)
Appsignal::EventFormatter. 