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 der Trace-Detailseite 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-Trace-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

Dry::Monitor-Events formatieren

Event-Formatter formatieren auch Events, die über Dry::Monitor-Notifications instrumentiert werden. Registrieren Sie den Formatter für die Dry::Monitor-Event-ID, gefolgt von .dry, sodass ein als sql instrumentiertes Event von dem für sql.dry registrierten Formatter formatiert wird. Der erste Wert, den der Formatter zurückgibt, bedeutet für diese Events etwas anderes. Für ein ActiveSupport::Notifications-Event ist es der Titel des Events. Für ein Dry::Monitor-Event ist es der Name des Events, und das Event wird ohne Titel in der Timeline aufgezeichnet.

class MyQueryFormatter
  def format(payload)
    [
      "query.my_library", # The event name, rather than the title
      payload[:query],
      Appsignal::EventFormatter::SQL_BODY_FORMAT
    ]
  end
end

Appsignal::EventFormatter.register("sql.dry", MyQueryFormatter)

Einen Event-Formatter deregistrieren

Deregistrieren Sie einen Formatter, damit AppSignal ihn nicht mehr für einen Event-Namen verwendet.

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

Verwenden Sie Appsignal::EventFormatter.registered?("event.custom"), um zu prüfen, ob für einen Event-Namen ein Formatter registriert ist.

Ä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

Dry::Monitor-Events formatieren

Einen Event-Formatter deregistrieren

Änderungen in Gem 2.5

​Einen Event-Formatter erstellen

​Beispiel-Event-Formatter

​Dry::Monitor-Events formatieren

​Einen Event-Formatter deregistrieren

​Änderungen in Gem 2.5

Einen Event-Formatter erstellen

Beispiel-Event-Formatter

Dry::Monitor-Events formatieren

Einen Event-Formatter deregistrieren

Änderungen in Gem 2.5