> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Event-Formatter

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][as_instrumentation]-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][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.

<Tip>
  **Hinweis**: Wenn es keine anderen Gründe gibt, die
  [`ActiveSupport::Notifications`][as_instrumentation]-Instrumentierung zu verwenden als
  die AppSignal-Instrumentierung, empfehlen wir, den [`Appsignal.instrument`-Helper][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.
</Tip>

## 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](/api/event-names).

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:

<CodeGroup>
  ```ruby Ruby theme={null}
  def format(payload)
    [
      "event title",
      "event body",
      Appsignal::EventFormatter::DEFAULT
    ]
  end
  ```
</CodeGroup>

1. 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.
2. Ein Event-Body (`String`)
   * Weitere Details, wie z. B. die Datenbankabfrage, die vom Event verwendet wurde.
3. 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.

<CodeGroup>
  ```sql SQL theme={null}
  -- 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 = ?
  ```
</CodeGroup>

<Warning>
  **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.
</Warning>

## Beispiel-Event-Formatter

<CodeGroup>
  ```ruby Ruby theme={null}
  # 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)
  ```
</CodeGroup>

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

<CodeGroup>
  ```ruby Ruby theme={null}
  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
  ```
</CodeGroup>

## Ä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](http://guides.rubyonrails.org/configuring.html#using-initializer-files) 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.

<CodeGroup>
  ```ruby Ruby theme={null}
  # 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
  ```
</CodeGroup>

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

<CodeGroup>
  ```ruby Ruby theme={null}
  class MyCustomEventFormatter
    def format(payload)
      [payload[:title], payload[:body], Appsignal::EventFormatter::DEFAULT]
    end
  end

  Appsignal::EventFormatter.register("event.custom", MyCustomEventFormatter)
  ```
</CodeGroup>

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

[as_instrumentation]: /ruby/instrumentation/instrumentation.html#activesupport-notifications

[instrument_helper]: /ruby/instrumentation/instrumentation.html#appsignal-instrumentation-helpers