Comment instrumenter votre application Ruby avec l'agent Ruby pour Elastic APM

Vous souhaitez que votre application Ruby envoie des indicateurs de performances vers un serveur APM ? C’est tout simple, aussi simple que d’installer le gestionnaire Rubygem elastic-apm. La plupart des intégrations sont directes, avec un support pour Rails et Rack intégré.

Néanmoins, il existe plusieurs méthodes pour ajouter davantage d’informations aux données et pour configurer vos propres instrumentations.

Ajout d’informations aux éléments déjà instrumentés

Pour ajouter davantage d’informations aux données que vous collectez déjà, Elastic APM propose quelques concepts intéressants.

Supposons que votre application soit construite sur le concept des entreprises, companies. Vous pourriez attribuer un diminutif de l’entreprise, current_company.short_name, à chaque transaction et à chaque erreur. Les balises sont, en effet, de simples paires clé-valeur qui sont indexées dans Elasticsearch et qu’il est possible de filtrer et d’interroger pour pouvoir couper et recouper les indicateurs de la façon souhaitée :

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

Ainsi, vous pourrez déterminer avec une extrême simplicité si des problèmes de performances ou des exceptions concernent uniquement certains clients.

Les utilisateurs représentent un autre concept largement étendu, qu’Elastic APM prend également en charge :

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

L’agent inclura les champs id, email et username de tous les éléments transmis. Vous pouvez, bien entendu, personnaliser les champs en fonction de ce qui est indiqué dans votre application.

Le module SpanHelpers

Si vous souhaitez surveiller la durée d’une méthode spécifique qui vous intéresse, vous pouvez vous servir du module SpanHelpers. Ce module propose deux méthodes : l’une par intervalles, span_method, et l’autre par classe d’intervalles, 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

Consultez les documentations sur le module SpanHelpers de l’agent Ruby pour Elastic APM.

Cette approche convient parfaitement si votre but est de mesurer un simple appel de méthode. Si vous souhaitez exercer un contrôle plus granulaire, appuyez-vous sur l’API d’utilisation générale.

Création manuelle de transactions et d’intervalles

Pour créer manuellement des transactions et des intervalles, l’agent fournit une API publique. L’agent utilise lui-même cette API en interne pour instrumenter la plupart des bibliothèques prises en charge.

Le premier élément dont vous aurez besoin est une transaction. Si vous êtes dans une requête de votre application Rails, dans une application Rack utilisant un intergiciel, ou dans une tâche en arrière-plan dans l’un des programmes d’exécution de tâches pris en charge, alors vous êtes très probablement déjà dans une transaction.

Si ce n’est pas le cas, créez une transaction comme suit :

ElasticAPM.start # if it isn't started already

begin
  transaction = ElasticAPM.start_transaction 'Optional name', 'optional.type'
  # C’est à vous qu’il revient de vérifier que les transactions ont pris fin.
  # Pour cela, nous utilisons begin/ensure.
ensure
  ElasticAPM.end_transaction
end

Une autre méthode consiste à utiliser une version avec blocage pour être sûr que la transaction prenne fin :

ElasticAPM.with_transaction do |transaction|
  # Si besoin, vous pouvez modifier la syntaxe de la transaction, par exemple :
  transaction.name = method_that_returns_the_name

  # Attention : si l’agent n’est pas démarré, la `transaction` est nulle mais le blocage est tout de même évalué.
end

Dans les transactions, les intervalles sont des éléments de travail individuels que réalise votre application. Si vous utilisez l’une des bibliothèques automatiquement instrumentées, tout ce que vous avez à faire est d’inclure ces éléments dans une transaction.

Si d’autres intervalles s’avèrent nécessaires, l’API met la transaction en correspondance :

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

# Ou la version avec blocage
ElasticAPM.with_span 'Hard work' do |span|
  # ...
end

Consultez les documentations sur l’agent Ruby pour Elastic APM pour en savoir plus sur l’API publique.

Facile à faire fonctionner, facile à déployer

Nous avons fait de notre mieux pour que la configuration initiale minimale de l’agent Ruby pour Elastic APM soit aussi simple que possible. Toute la procédure que nous avons vue ci-dessus n’est pas obligatoire. Dans tous les cas, vous collecterez un grand nombre d’informations utiles.

En revanche, si vous avez envie de mettre la main à la pâte en disséquant chaque partie de votre “bête“ (c’est-à-dire votre application !), Elastic APM fournit des outils qui vous y aideront.

Lancez-vous !

Alors, comment fonctionne votre application Ruby ? À quels endroits prend-elle du temps ? Sur quel aspect devriez-vous vous concentrer pour améliorer l’expérience utilisateur ? Elastic APM et l’agent Ruby peuvent vous aider à répondre à toutes ces questions, et bien plus encore. Instrumentez votre application, puis téléchargez la Suite Elastic ou exécutez-la en local, ou envoyez vos traces à Elasticsearch Service sur Elastic Cloud avec une version d’essai gratuite, qui inclut un serveur APM. Comme toujours, si vous avez des questions, des idées, des réflexions ou des inquiétudes dont vous souhaitez nous faire part, contactez-nous sur le forum de discussion.