Instrumentieren Sie Ihre Ruby-App mit dem Elastic APM Ruby Agent

By
Mikkel Malmberg

Sie können bereits mit dem Versand von Leistungsmetriken aus Ihrer Ruby-App an den APM Server beginnen, indem Sie einfach nur den Rubygem elastic-apm installieren. Die meisten Integrationen sind Plug-and-Play, und Rails und Rack werden ebenfalls unterstützt.

Sie haben jedoch verschiedene Möglichkeiten, um die Daten zu ergänzen oder Ihre eigenen benutzerdefinierten Instrumentierungen hinzuzufügen.

Zusätzliche Informationen für bereits instrumentierte Komponenten

Elastic APM verwendet verschiedene Konzepte, mit denen Sie Ihre bereits erfassten Daten anreichern können.

Angenommen, Ihre App befasst sich mit dem Konzept von companies, dann könnten Sie current_company.short_name zu allen Transaktionen und Fehlern zuordnen. Tags sind einfache Schlüssel-Wert-Paare, werden in Elasticsearch indexiert und können daher gefiltert und abgefragt werden, damit Sie Ihre Metriken nach Belieben untersuchen und zerlegen können:

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

Auf diese Weise können Sie leichter erkennen, ob sich bestimmte Leistungsprobleme oder Ausnahmen nur auf einen Teil Ihrer Benutzer auswirken.

Nur Anfragen für die Company Opbeans auflisten

Benutzer sind ein weiteres gängiges Konzept, für das Elastic APM einen passenden Ort bietet:

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

Der Agent bindet die Felder id, email und username aller übergebenen Objekte ein. Sie können die Felder selbstverständlich an beliebige Entitäten in Ihrer App anpassen.

Das SpanHelpers-Modul

Wenn Sie eine bestimmte Methode im Blick haben, deren Dauer Sie messen möchten, können Sie das SpanHelpers-Modul verwenden. Es enthält zwei Methoden: span_method und 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 \n  def do_the_work
    # ...
  end
end

Weitere Infos finden Sie in den SpanHelpers-Dokumenten für den Elastic APM Ruby Agent.

Dieser Ansatz ist sehr hilfreich, um einen einfachen Methodenaufruf zu messen. Für eine differenziertere Kontrolle können Sie die allgemeine API verwenden.

Manuelles Erstellen von Transaktionen und Spans

Der Agent stellt eine öffentliche API bereit, mit der Sie Transaktionen und Spans manuell erstellen können. Der eigentliche Agent verwendet diese API intern, um einen Großteil der unterstützten Bibliotheken zu instrumentieren.

Zunächst benötigen Sie eine Transaktion. Wenn Sie sich in einer Anforderung in Ihrer Rails-App, einer Rack-App mit Middleware oder einem Hintergrundauftrag in einem der unterstützten Auftragsausführer befinden, dann verwenden Sie höchstwahrscheinlich bereits eine Transaktion.

Andernfalls können Sie eine Transaktion wie folgt erstellen:

ElasticAPM.start # if it isn't started already

begin
  transaction = ElasticAPM.start_transaction 'Optional name', 'optional.type'
  # Sie müssen garantieren, dass die Transaktionen beendet werden.
  # Dazu umschließen wir sie mit begin..ensure.
ensure
  ElasticAPM.end_transaction
end

Alternativ können Sie dasselbe mit einem Block erreichen, der dafür sorgt, dass die Transaktion beendet wird:

ElasticAPM.with_transaction do |transaction|
  # Bei Bedarf können Sie die enthaltene Transaktion ändern:
  transaction.name = method_that_returns_the_name

  # Achtung: Wenn der Agent nicht gestartet wird, ist `transaction` gleich `nil`, aber der Block wird trotzdem ausgewertet
end

Spans sind die Bausteine innerhalb von Transaktionen, die die Aufgaben Ihrer App erledigen. Wenn Sie eine der automatisch instrumentierten Bibliotheken verwenden, reicht es aus, diese mit einer Transaktion zu umschließen.

Wenn Sie zusätzliche Spans brauchen, passt sich die API an die Transaktion an:

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

# Oder in Blockform
ElasticAPM.with_span 'Hard work' do |span|
  # ...
end

Warum dauert das so lange … oh

Weitere Hinweise zur öffentlichen API finden Sie in der Dokumentation zum APM Ruby Agent.

Einfach einzusetzen, einfach zu erweitern

Wir haben uns größte Mühe gegeben, die Ersteinrichtung des Ruby APM Agent so einfach wie möglich zu gestalten. Sie müssen keinen der oben genannten Schritte ausführen und erhalten vermutlich trotzdem eine Menge an nützlichen Informationen.

Wenn Sie sich jedoch die Hände schmutzig machen und Ihre App bis in den letzten Winkel sezieren möchten, dann bietet Elastic APM auch dafür die passenden Tools.

Probieren Sie es aus

Wie gut läuft Ihr Ruby? Wo geht Zeit verloren? Worauf sollten Sie sich beim nächsten Sprint konzentrieren, um das Benutzererlebnis zu verbessern? Elastic APM und der Ruby Agent können all diese und viele weitere Fragen beantworten. Instrumentieren Sie Ihre App und laden Sie den Elastic Stack herunter, um ihn lokal auszuführen, oder senden Sie Ihre Traces an den Elasticsearch Service in der Elastic Cloud mit einer kostenlosen Testversion, die auch einen APM Server umfasst. Falls Sie Fragen, Ideen, Anregungen oder Bedenken haben, können Sie diese wie immer im Diskussionsforum besprechen.