Event formatters

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.

Einen Event-Formatter erstellen

Ein AppSignal-Event-Formatter ist eine Klasse mit einer Instanzmethode, 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.

Beispiel-Event-Formatter

# 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)

Wenn Sie dann einen Codeblock instrumentieren, verwenden Sie den Event-Namen, der für Ihren benutzerdefinierten Event-Formatter registriert ist.

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

Beim neuen Setup wurde der register-Aufruf aus der Klasse selbst extrahiert, sodass er stattdessen direkt auf der EventFormatter-Klasse registriert werden kann.

class MyCustomEventFormatter
  def format(payload)
    [payload[:title], payload[:body], Appsignal::EventFormatter::DEFAULT]
  end
end

Appsignal::EventFormatter.register("event.custom", MyCustomEventFormatter)

Das bedeutet auch, dass Ihre EventFormatter keine Unterklasse der Appsignal::EventFormatter-Klasse mehr sein müssen.

SDKs & Telemetrie

Sprach-SDKs

Telemetrie-Tools

Einen Event-Formatter erstellen

Beispiel-Event-Formatter

Änderungen in Gem 2.5

​Einen Event-Formatter erstellen

​Beispiel-Event-Formatter

​Änderungen in Gem 2.5

Einen Event-Formatter erstellen

Beispiel-Event-Formatter

Änderungen in Gem 2.5