Como instrumentar aplicações Ruby com o agente Ruby do Elastic APM

Enviar métricas de desempenho de aplicações Ruby ao APM Server pode ser tão fácil quanto instalar o Rubygem elastic-apm. A maioria das integrações é plug-n-play, e o suporte a Rails e Rack é oferecido internamente.

Entretanto, há várias maneiras de adicionar informações aos dados, além de maneiras de configurar suas próprias instrumentações personalizadas.

Adição de informações às partes já instrumentadas

Para adicionar mais informações aos dados que você já está reunindo, o Elastic APM tem alguns conceitos.

Supondo que a aplicação foi desenvolvida em torno do conceito de companies, você poderia atribuir current_company.short_name a cada transação e erro. As marcas são pares key-value simples e são indexadas no Elasticsearch, por isso podem ser filtradas e consultadas, assim você poderá segmentar as métricas do jeito que quiser:

class ApplicationController < ActionController::Base
  before_action do
    ElasticAPM.set_label :company, current_company.short_name
  end
end

Isso permitirá ver facilmente se determinados problemas de desempenho ou exceções estão afetando somente alguns de seus clientes.

Os usuários são outro conceito disseminado, e o Elastic APM tem um lugar reservado para eles também:

class ApplicationController < ActionController::Base
  before_action do
    ElasticAPM.set_label :company_id, current_company.id
    ElasticAPM.set_user current_user
  end
end

O agente incluirá os campos id, email e username de qualquer informação repassada. Evidentemente você pode personalizar os campos para qualquer nome que eles tenham em seu aplicativo.

O módulo SpanHelpers

Se você estiver atento a um método específico cuja duração deseja rastrear, poderá usar o módulo SpanHelpers. Ele oferece dois métodos: span_method e span_class_method.

class ThingsController < ApplicationController
  include ElasticAPM::SpanHelpers

  # ...

  def do_the_work
    # ...
  end
  span_method :do_the_work

  def self.do_other_work
    # ... 
  end
  span_class_method :do_other_work

  # ... alternative syntax for newer versions of Ruby

  span_method \
  def do_the_work
    # ...
  end
end

Veja os documentos SpanHelpers do agente Ruby do Elastic APM.

Essa abordagem é excelente se o que você quer medir é uma simples chamada de método. Se quiser ter um controle mais granular, existe a API de utilização geral.

Criação manual de transações e durações

Para criar transações e durações manualmente, o agente fornece uma API pública. O agente em si usa essa API internamente para instrumentar a maioria das bibliotecas com suporte.

A primeira coisa de que você precisará é transaction. Se você estiver em uma solicitação no aplicativo Rails, no aplicativo Rack usando middleware ou em um trabalho em segundo plano em um dos executores de trabalho com suporte, será mais provável que já esteja em uma transação.

Se não estiver, crie uma transação como esta:

ElasticAPM.start # if it isn't started already

begin
  transaction = ElasticAPM.start_transaction 'Optional name', 'optional.type'
  # É de sua responsabilidade garantir que as transações sejam encerradas.
  # Para garantir que façamos isso, aplicamos wrap em begin..ensure.
ensure
  ElasticAPM.end_transaction
end

Como alternativa, há uma versão de bloco do mesmo que garante o encerramento posterior:

ElasticAPM.with_transaction do |transaction|
  # se precisar, você pode alterar a transação interna, por exemplo:
  transaction.name = method_that_returns_the_name

  # esteja ciente de que, se o agente não foi iniciado, `transaction` será nulo, mas o bloco ainda será avaliado
end

Dentro das transações, spans são as partes individuais de trabalho que o aplicativo executa. Se você estiver usando qualquer uma das bibliotecas instrumentadas automaticamente, bastará aplicar wrap nelas em uma transação.

Se precisar de durações adicionais, a API corresponderá à transação:

begin
  span = ElasticAPM.start_span 'Required name', 'optional.type'
ensure
  ElasticAPM.end_span
end

# Ou o bloco de
ElasticAPM.with_span 'Hard work' do |span|
  # ...
end

Veja os documentos do agente Ruby do APM para a API pública.

Fácil de usar, fácil de expandir

Demos o máximo para facilitar a instalação inicial mínima do agente Ruby do APM o máximo possível. Se você não quiser, não precisará de nenhuma das informações anteriores e ainda assim, muito provavelmente, obterá muitas informações úteis.

Entretanto, se quiser colocar a mão na massa para dissecar cada parte do aplicativo, o Elastic APM também fornecerá as ferramentas necessárias para isso.

Experimente

O Ruby está executando bem? Onde ele está passando o tempo? Onde você deve concentrar a próxima rodada para melhorar a experiência dos usuários? O Elastic APM e o agente Ruby podem ajudar a responder a todas essas dúvidas e muito mais. Faça instrumentação do aplicativo e faça download do Elastic stack e execute localmente ou envie os rastreamentos ao Elasticsearch Service no Elastic Cloud com uma avaliação grátis, que inclui um servidor APM. Como sempre, se você tiver alguma dúvida, ideia, opinião ou preocupação, acesse o fórum Discuss.