Ruby instrumentation personnalisée

Léagent New Relic Ruby collecte automatiquement de nombreuses métriques. Il comprend également une API que vous pouvez utiliser pour collecter des métriques supplémentaires sur votre application. Si vous voyez de grands segments Application Code dans les détails de trace de transaction, instrumentation personnalisée peut donner une image plus complète de ce qui se passe dans votre application. Pour plus de détails sur toutes les méthodes API disponibles, veuillez consulter notre documentation sur l'agent APIRuby .

Méthode traceur

Le moyen le plus simple de capturer une instrumentation personnalisée consiste à tracer les appels vers une méthode particulière. Le suivi d'une méthode comme décrit ci-dessous insérera un nœud supplémentaire dans votre trace de transaction pour chaque invocation de cette méthode, fournissant plus de détails sur la destination du temps dans vos transactions.

Cette option est particulièrement utile lorsque vous êtes certain qu'une transaction existe déjà. La méthode traceur vous donne un niveau de granularité supplémentaire dans le contexte de quelque chose déjà instrumenté par l'agent. Si vous n'êtes pas sûr qu'une transaction existe, consultez Suivi des points d'entrée des transactions.

Les traceurs de méthodes sont des sondes logicielles que vous pouvez placer sur une méthode de n'importe quelle classe. Les sondes utilisent le module prepending pour s'insérer lors de l'exécution des méthodes cibles et collecter instrumentation personnalisées sur leurs performances.

Traçage dans les définitions de classe

La méthode traceur peut être utilisée dans les définitions de classe normales, à condition que la méthode cible ait été définie en premier :

require 'new_relic/agent/method_tracer'
class Foo
  include ::NewRelic::Agent::MethodTracer

  def generate_image
    ...
  end

  add_method_tracer :generate_image, 'Custom/generate_image'
end

Pour instrumenter une méthode de classe, ajoutez la méthode traceur dans le singleton de classe :

require 'new_relic/agent/method_tracer'
class Foo
  def self.generate_image
     ...
  end

  class << self
    include ::NewRelic::Agent::MethodTracer

    add_method_tracer :generate_image, 'Custom/generate_image'
  end
end

La méthode add_method_tracer prend un nom métrique facultatif et un hachoir d'options. Pour plus d'informations, consultez add_method_tracer dans le New Relic RubyDoc.

Traçage des initialiseurs

Pour Rails, une manière courante d'ajouter de l'instrumentation est de créer un initialiseur et de « patcher » les directives d'instrumentation.

Par exemple, pour ajouter un traceur de méthode à MyCache#get:

1. Assurez-vous que la classe MyCache est chargée avant d'ajouter la méthode traceur.

2. Ajoutez ce qui suit dans un fichier nommé config/initializers/rpm_instrumentation.rb:

   require 'new_relic/agent/method_tracer'
   
   MyCache.class_eval do
     include ::NewRelic::Agent::MethodTracer
   
     add_method_tracer :get
   end

   Copier

Traçage de blocs de code

Parfois, une méthode unique est si complexe que le suivi du temps global ne donne pas suffisamment de détails. Si vous avez une transaction existante pour laquelle vous souhaitez avoir des informations plus détaillées sur une méthode individuelle, vous pouvez envelopper un bloc de code avec un traceur. Appelez trace_execution_scoped en passant le code à trace sous forme de bloc :

extend ::NewRelic::Agent::MethodTracer

def slow_action
  self.class.trace_execution_scoped(['Custom/slow_action/beginning_work']) do
    # do stuff and report execution time with a custom metric name
  end

  # more stuff, whose time will be "blamed" to slow_action
end

Pour plus d'informations, consultez add_method_tracer dans le New Relic RubyDoc. Si vous n'êtes pas sûr qu'une transaction existe déjà ou si vous devez en démarrer une nouvelle, consultez une section de code sous Instrumentation personnalisée avancée.

Dénomination des transactions

Les transactions instrumentées sont utilisées pour déterminer le débit et le temps de réponse global de votre application. Le nom de la méthode et de la classe seront utilisés pour le nom de la transaction tel que signalé à New Relic. Pour plus d'informations, voir Affichage de la trace de transaction.

Normalement, l'agent choisit automatiquement le nom de la transaction. Si vous souhaitez modifier le nom d'une transaction alors qu'elle est en cours d'exécution, utilisez NewRelic::Agent.set_transaction_name et le NewRelic::Agent.get_transaction_name correspondant.

Ceci est utile si vous souhaitez segmenter votre transaction en fonction de certains critères. Par exemple, si vous souhaitez modifier le nom de la transaction par format de réponse dans Rails :

class UsersController
  def index
    @users = User.all
    respond_to do |format|
      format.html
      format.json do
        NewRelic::Agent.set_transaction_name('Users/index.json')
        render :json => @users
      end
      format.xml do
        NewRelic::Agent.set_transaction_name('Users/index.xml')
        render :xml => @users
      end
    end
  end
end

Le changement de nom des transactions peut également être utilisé pour segmenter vos requests autour de certains critères commerciaux. Par exemple, vous pouvez segmenter une transaction en « Gros clients » et « Petits clients » avec un code comme celui-ci :

class UsersController

  before_filter :segment_new_relic_by_customer_size

  def segment_new_relic_by_customer_size
    new_relic_name = NewRelic::Agent.get_transaction_name
    if current_user.big_customer?
      NewRelic::Agent.set_transaction_name("#{new_relic_name} - big customer")
    else
      NewRelic::Agent.set_transaction_name("#{new_relic_name} - small customer")
    end
  end

end

Suivi des points d'entrée des transactions

En règle générale, l'agent sera en mesure d'identifier les transactions au sein de votre application, mais si vous n'utilisez pas de framework pris en charge ou si vous souhaitez enregistrer des transactions que l'agent n'enregistre pas automatiquement, vous pouvez définir des méthodes comme étant des points d'entrée de transaction :

class Controller
  include NewRelic::Agent::Instrumentation::ControllerInstrumentation

  def transaction
    # execute a transaction
  end
  add_transaction_tracer :transaction
end

Pour instrumenter une méthode de classe, ajoutez la méthode traceur dans le singleton de classe :

class Controller
  include NewRelic::Agent::Instrumentation::ControllerInstrumentation

  class << self
    def transaction
      # execute a transaction
    end
    add_transaction_tracer :transaction
  end
end

instrumenté transaction non web

Outre le traçage au niveau de la méthode, vous pouvez instrumenter les transactions non Web, telles que les tâches en arrière-plan, avec le même niveau de détail de transaction et d'erreur que les transactions Web. Pour plus d'informations, voir monitoring des processus d'arrière-plan Ruby et daemon.

Application automatique de la méthode traceur via la configuration

Avec l'agent Ruby New Relic v9.14.0 et supérieur, la méthode traceur peut être appliquée automatiquement par l'agent pour toute méthode Ruby définie dans la configuration de l'agent (définie via le fichier configuration YAML ou les variables d'environnement).

Le paramètre de configuration :automatic_custom_instrumentation_method_list peut être utilisé pour définir une liste de méthodes Ruby entièrement qualifiées (avec espace de noms) pour lesquelles l'agent tentera d'ajouter un traceur. Cela ne nécessite aucune modification du code des classes qui définissent les méthodes.

La liste doit être un éventail de chaînes CLASS#METHOD (pour les méthodes instance ) et/ou CLASS.METHOD (pour les méthodes de classe).

Utilisez des noms de classe entièrement qualifiés (en utilisant le délimiteur :: ) qui incluent tout espace de noms de module ou de classe.

Voici une source de code Ruby qui définit une méthode d'instance render_png pour une classe Image et une méthode de classe notify pour une classe User, toutes deux dans un espace de nommage de module MyCompany :

module MyCompany
  class Image
    def render_png
      # code to render a PNG
    end
  end

  class User
    def self.notify
      # code to notify users
    end
  end
end

Étant donné le code source, le fichier de configuration newrelic.yml peut demander une instrumentation pour ces deux méthodes comme suit :

automatic_custom_instrumentation_method_list:
  - MyCompany::Image#render_png
  - MyCompany::User.notify

Cet exemple configuration utilise la syntaxe éventail YAML pour spécifier les deux méthodes. Alternativement, vous pouvez utiliser une chaîne délimitée par des virgules :

automatic_custom_instrumentation_method_list: 'MyCompany::Image#render_png, MyCompany::User.notify'

Les espaces autour des virgules dans la liste sont facultatifs. Lors de la configuration de l'agent avec une liste de méthodes via la variable d'environnement NEW_RELIC_AUTOMATIC_CUSTOM_INSTRUMENTATION_METHOD_LIST , utilisez ce format de chaîne délimitée par des virgules :

$
export NEW_RELIC_AUTOMATIC_CUSTOM_INSTRUMENTATION_METHOD_LIST='MyCompany::Image#render_png, MyCompany::User.notify'

L'entrée YAML ou la configuration de la variable d'environnement est tout ce qui est nécessaire. Avec cette approche, il n’est pas nécessaire d’ajouter l’une des lignes de code require, include ou add_method_tracer à l’application.

instrumentation avancée personnalisée

Lors du traçage de code non instrumenté automatiquement par l'agent, la méthode standard traceur sera généralement suffisante.

Cependant, vous avez parfois besoin d’ instrumenter quelque chose de plus complexe qu’un simple appel de méthode. Par exemple, vous souhaiterez peut-être instrumenter quelques lignes de code dans une méthode, ou vous souhaiterez peut-être démarrer une transaction dans une partie de votre code et la terminer ailleurs.

Le module traceur, introduit dans la version 6.0 de l'agent, fournit une API flexible qui vous permet de créer des transactions et des segments ainsi que d'interagir avec la transaction en cours.

instrumenté une section de code

Pour instrumenter une section de code, enveloppez le code dans un bloc, puis transmettez le bloc à la méthode Tracer.in_transaction. L'agent s'assurera qu'une transaction existe et créera un segment à l'intérieur de celle-ci pour le code à l'intérieur du bloc.

require 'new_relic/agent/tracer'

def long_and_complex_process
  expensive_setup

  NewRelic::Agent::Tracer.in_transaction(
    partial_name: 'Complex/process',
    category: :task
  ) do
    code_to_be_instrumented
  end

  expensive_teardown
end

Démarrer une transaction ou un segment

Si vous devez démarrer une transaction à un endroit de votre code mais la terminer à un autre (comme cela peut arriver avec un événement basé sur le rappel), appelez NewRelic::Agent::Tracer.start_transaction_or_segment. Vous must appelez finish sur la valeur de retour de cette méthode :

class MyEventWatcher
  def event_started
    @transaction = NewRelic::Agent::Tracer.start_transaction_or_segment(
      partial_name: 'MyEventWatcher/my_event',
      category:     :task)
  end

  def event_completed
    @transaction.finish
  end
end

Pour plus d'informations, consultez Tracer#start_transaction_or_segment dans le New Relic RubyDoc.

instrumenté Fils

Dans la version 8.7.0 et supérieure, utilisez la classe NewRelic::TracedThread dans les applications pour créer des threads instrumentés par New Relic.

Utilisez cette classe en remplacement de la classe native Thread . Consultez notre documentation API TracedThread pour plus de détails.