Pular para o conteúdo principal
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 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. 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.
Nota: Se não houver outros motivos para usar a instrumentação do ActiveSupport::Notifications além da instrumentação do AppSignal, recomendamos usar o helper Appsignal.instrument 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.

​
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. 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: 
def format(payload)
  [
    "event title",
    "event body",
    Appsignal::EventFormatter::DEFAULT
  ]
end
  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.
-- 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 = ?
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.

​
Exemplo de formatador de eventos

# 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)
Então, ao instrumentar um bloco de código, use o nome do evento registrado para o seu formatador de eventos personalizado. 
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

​
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. 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. 
# 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
Com a nova configuração, a chamada register foi extraída da própria classe, então pode ser registrada diretamente na classe EventFormatter. 
class MyCustomEventFormatter
  def format(payload)
    [payload[:title], payload[:body], Appsignal::EventFormatter::DEFAULT]
  end
end

Appsignal::EventFormatter.register("event.custom", MyCustomEventFormatter)
Isso também significa que seus EventFormatters não precisam mais ser uma subclasse da classe Appsignal::EventFormatter.