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

# Formatadores de eventos

Formatadores de eventos são classes helper para formatar metadados de eventos para transactions do AppSignal. Na gem do AppSignal, formatadores de eventos são usados para formatar metadados de eventos da instrumentação do [ActiveSupport::Notifications][as_instrumentation] para metadados de evento do AppSignal.

Quando um bloco de código é instrumentado por ActiveSupport::Notifications, o AppSignal registrará o evento nas transactions, assim como faria para o [helper `Appsignal.instrument`][instrument_helper]. Os formatadores de eventos permitem que os dados passados para a chamada do método `ActiveSupport::Notifications.instrument` sejam formatados para eventos do AppSignal.

Os metadados dos eventos formatados pelos formatadores de eventos ficarão visíveis nas páginas de detalhes de incidentes de desempenho na timeline de eventos. Passe o mouse sobre um evento específico e o pop-up que aparece ao passar o mouse mostrará detalhes como o banco de dados exato sendo consultado ou a query que foi executada.

<Tip>
  **Nota**: Se não houver outros motivos para usar
  a instrumentação do [`ActiveSupport::Notifications`][as_instrumentation] além
  da instrumentação do AppSignal, recomendamos usar o [helper
  `Appsignal.instrument`][instrument_helper] para instrumentação. Usar
  `ActiveSupport::Notifications` adiciona mais overhead do que chamar diretamente
  o `AppSignal.instrument`. Nenhum formatador de eventos será necessário também, pois
  o `AppSignal.instrument` aceita que os metadados sejam definidos diretamente.
</Tip>

## Criando um formatador de eventos

Um formatador de eventos do AppSignal é uma classe com um método de instância, `format`. Esse método format recebe o Hash de payload do evento e precisa retornar um Array com três valores.

É possível adicionar um formatador de eventos para bibliotecas que usam a instrumentação do ActiveSupport::Notifications, mas verifique se já não existe um formatador de eventos registrado para isso.

Também é possível criar um formatador de eventos para seus próprios eventos. Ao adicionar nomes de eventos próprios, atente-se às diretrizes de [nomeação de eventos](/api/event-names).

Cada formatador de eventos recebe um Hash de "payload" com metadados de evento, a partir do qual o formatador de eventos pode formatar os metadados para o evento no AppSignal. Esses metadados de evento do AppSignal precisam ser retornados pelo formatador de eventos nesta ordem em um Array:

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

1. Um título de evento (`String`)
   * Um título mais descritivo de um evento, como `"Fetch current user"` ou `"Fetch blog post comments"`. Ele aparecerá ao lado do nome do evento na árvore de eventos na página de amostra de desempenho para fornecer um pouco mais de contexto sobre o que está acontecendo.
2. Um body de evento (`String`)
   * Mais detalhes, como a query do banco de dados usada pelo evento.
3. Um formato do body do evento (`Integer`)
   * O formato do body suporta formatadores para sanitizar os dados fornecidos no argumento `body` e remover quaisquer dados sensíveis do valor. Atualmente, há dois valores suportados para o argumento `body_format`.
     * `Appsignal::EventFormatter::DEFAULT`
       * Este valor padrão indicará ao AppSignal para deixar o valor intacto e não sanitizar nenhum dado dele.
     * `Appsignal::EventFormatter::SQL_BODY_FORMAT`
       * O valor `SQL_BODY_FORMAT` indicará ao AppSignal para passar seus dados pelo sanitizador de SQL e sanitizar quaisquer valores em queries SQL.

<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>
  **Aviso**: o formatador de eventos não tem tratamento de exceções em volta dele.
  Se o formatador de eventos personalizado levantar um erro, ele fará a requisição web
  ou o background job crashar.
</Warning>

## Exemplo de formatador de eventos

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

Então, ao instrumentar um bloco de código, use o nome do evento registrado para o seu formatador de eventos personalizado.

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

## Mudanças na gem 2.5

Na versão `2.5.2` da gem AppSignal para Ruby, foram feitas algumas mudanças em como os formatadores de eventos são registrados. O método antigo de registrar formatadores de eventos foi descontinuado nesta release e será removido na versão `3.0` da gem Ruby.

O novo método de registrar EventFormatters permitirá que formatadores personalizados sejam registrados após o AppSignal ter sido carregado. Isso permite que EventFormatters sejam registrados em [initializers do Rails](http://guides.rubyonrails.org/configuring.html#using-initializer-files).

Na versão `2.5.1` e anteriores da gem, é possível registrar um formatador de eventos como no exemplo abaixo, chamando o método `register` na própria classe.

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

Com a nova configuração, a chamada register foi extraída da própria classe, então pode ser registrada diretamente na classe EventFormatter.

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

Isso também significa que seus EventFormatters não precisam mais ser uma subclasse da classe `Appsignal::EventFormatter`.

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

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