Event-Formatter sind Helper-Klassen, um Event-Metadaten für AppSignal-Transaktionen zu formatieren. Im AppSignal-Gem werden Event-Formatter verwendet, um Event-Metadaten aus ActiveSupport::Notifications-Instrumentierung-Events in AppSignal-Event-Metadaten zu formatieren.
Wenn ein Codeblock durch ActiveSupport::Notifications instrumentiert wird, zeichnet AppSignal das Event auf den Transaktionen auf, genau wie bei dem Appsignal.instrument-Helper. Event-Formatter ermöglichen es, die an den ActiveSupport::Notifications.instrument-Methodenaufruf übergebenen Daten für AppSignal-Events zu formatieren.
Die Metadaten für die von den Event-Formattern formatierten Events sind auf den Detailseiten von Performance-Incidents in der Event-Timeline sichtbar. Fahren Sie mit der Maus über ein bestimmtes Event, und das Pop-up beim Mouseover zeigt Details wie die genau abgefragte Datenbank oder die ausgeführte Abfrage.
Hinweis: Wenn es keine anderen Gründe gibt, die
ActiveSupport::Notifications-Instrumentierung zu verwenden als
die AppSignal-Instrumentierung, empfehlen wir, den Appsignal.instrument-Helper für die Instrumentierung zu verwenden. Die Verwendung von
ActiveSupport::Notifications fügt mehr Overhead hinzu als der direkte Aufruf von
AppSignal.instrument. Es wird auch kein Event-Formatter benötigt, da
AppSignal.instrument die Metadaten direkt akzeptiert. format. Diese format-Methode erhält das Event-Payload-Hash und muss ein Array mit drei Werten zurückgeben.
Es ist möglich, Event-Formatter für Bibliotheken hinzuzufügen, die die ActiveSupport::Notifications-Instrumentierung verwenden, achten Sie jedoch darauf, dass nicht bereits ein Event-Formatter dafür registriert ist.
Es ist auch möglich, einen Event-Formatter für Ihre eigenen Events zu erstellen. Beachten Sie beim Hinzufügen Ihrer eigenen Event-Namen die Richtlinien zur Event-Benennung.
Jeder Event-Formatter erhält ein Event-Metadaten-”payload”-Hash, aus dem der Event-Formatter die Metadaten für das Event in AppSignal formatieren kann. Diese AppSignal-Event-Metadaten müssen vom Event-Formatter in dieser Reihenfolge in einem Array zurückgegeben werden:
def format(payload)
[
"event title",
"event body",
Appsignal::EventFormatter::DEFAULT
]
end
- Ein Event-Titel (
String)
- Ein beschreibenderer Titel eines Events, wie z. B.
"Fetch current user" oder "Fetch blog post comments". Er erscheint neben dem Event-Namen im Event-Baum auf der Performance-Sample-Seite, um etwas mehr Kontext zu dem zu liefern, was gerade passiert.
- Ein Event-Body (
String)
- Weitere Details, wie z. B. die Datenbankabfrage, die vom Event verwendet wurde.
- Ein Event-Body-Format (
Integer)
- Body-Format unterstützt Formatter, um die im
body-Argument angegebenen Daten zu bereinigen und sensible Daten aus dem Wert zu entfernen. Es gibt derzeit zwei unterstützte Werte für das body_format-Argument.
Appsignal::EventFormatter::DEFAULT
- Dieser Standardwert weist AppSignal an, den Wert unverändert zu lassen und keine Daten daraus zu bereinigen.
Appsignal::EventFormatter::SQL_BODY_FORMAT
- Der Wert
SQL_BODY_FORMAT weist AppSignal an, Ihre Daten durch den SQL-Sanitizer zu führen und alle Werte in SQL-Abfragen zu bereinigen.
-- 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 = ?
Warnung: Der Event-Formatter hat kein umschließendes Exception-Handling.
Wenn der benutzerdefinierte Event-Formatter einen Fehler auslöst, stürzt der Webrequest
oder Hintergrundjob ab.
# 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
Änderungen in Gem 2.5
In AppSignal für Ruby-Gem-Version 2.5.2 wurden einige Änderungen daran vorgenommen, wie Event-Formatter registriert werden. Die alte Methode zum Registrieren von Event-Formattern wurde in diesem Release als veraltet markiert und wird in Version 3.0 des Ruby-Gems entfernt.
Die neue Methode zum Registrieren von EventFormattern ermöglicht es, benutzerdefinierte Formatter nach dem Laden von AppSignal zu registrieren. Dies ermöglicht es, EventFormatter in Rails-Initializern zu registrieren.
In Gem-Version 2.5.1 und älter ist es möglich, einen Event-Formatter wie im folgenden Beispiel zu registrieren, indem die register-Methode in der Klasse selbst aufgerufen wird.
# 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-Klasse mehr sein müssen. 