Rubyカスタムインストゥルメンテーション

New Relic Rubyエージェントは、多くのメトリクスを自動的に収集します。また、アプリケーションに関する追加のメトリクスを収集するために使用できる API も含まれています。境界トレースの詳細に大きなApplication Codeセグメントが表示される場合、カスタムインストゥルメンテーションはアプリケーションで何が起こっているかをより完全に把握できます。利用可能なすべてのAPIメソッドの詳細については、 Rubyドキュメントを参照してください。

ヒント

あまりにも大量のメトリクスを収集すると、ご利用のアプリケーションとNew Relicのパフォーマンスに影響が及ぶ可能性があります。データ関連の問題を回避するため、カスタムインストゥルメンテーションが採用する固有のメトリクスの合計数を2000未満に維持してください。

メソッドトレーサー

カスタムインストゥルメンテーションをキャプチャーできる最も簡単な方法は、特定のメソッドへのコールをトレースすることです。以下に解説したメソッドでトレースすることで、そのメソッドの各呼び出しに対してトランザクショントレースに追加ノードが挿入されます。こうして、トランザクションの時間進行をより詳しく把握できるようになります。

これは、トランザクションがすでに存在していると思われる場合に最適です。メソッドトレーサーを使用すると、エージェントによってすでにインストゥルメントされているもののコンテキスト内に、レベルの粒度が追加されます。トランザクションが存在するかどうか不明な場合は、トランザクションエントリポイントのトレーシングを参照してください。

メソッドトレーサーは、あらゆるクラスのメソッドに取り付け可能なソフトウェアプローブです。このプローブは、ターゲットメソッドを実行してパフォーマンスに関するカスタムインストゥルメンテーションを収集する際、モジュールの先頭に追加して自らを挿入します。

クラス定義におけるトレーシング

ターゲットメソッドが先に定義されている限り、メソッドトレーサーを通常のクラス定義内で使用できます：

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

クラスメソッドをインストゥルメントするには、クラスシングルトンにメソッドトレーサーを追加します：

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

add_method_tracerメソッドは、任意のメトリック名とオプションのハッシュを取ります。詳しくは、New Relic RubyDocのadd_method_tracerを参照してください。

初期化子のトレーシング

Railsの場合、初期化子を作成してインストゥルメンテーションディレクティブに「モンキーパッチ」を適用するのが一般的なインストゥルメンテーションの追加方法となります。

たとえば、MyCache#getにメソッドトレーサーを追加するには：

必ず、メソッドトレーサーを追加する前にMyCacheクラスがロードされていることを確認してください。

config/initializers/rpm_instrumentation.rbという名前のファイルに以下を追加します。

require 'new_relic/agent/method_tracer'

MyCache.class_eval do
  include ::NewRelic::Agent::MethodTracer

  add_method_tracer :get
end

コードブロックのトレーシング

場合によっては、1 つの方法が非常に複雑なため、全体の時間を追跡しても十分な詳細が得られないことがあります。個々のメソッドに関するより詳細な情報が必要な既存のトランザクションがある場合は、コードのブロックをトレーサーでラップできます。 trace_execution_scopedを呼び出して、トレースするコードをブロックとして渡します。

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

詳細については、 New Relic RubyDoc の add_method_tracer を参照してください。トランザクションが既に存在するかどうか、または新しいトランザクションを開始する必要があるかどうかがわからない場合は、「高度なカスタムインストゥルメント」のコードのセクションを参照してください。

トランザクションの命名

ご利用アプリケーションのスループットと合計レスポンスタイムを判断するには、インストゥルメントされたトランザクションを使用します。メソッドおよびクラス名が、New Relicにレポートされたトランザクション名として使用されます。詳しくはトランザクショントレースを表示するをご覧ください。

通常は、エージェントが自動的にトランザクション名を選択します。トランザクションの実行中にトランザクションの名前を変更する場合は、NewRelic::Agent.set_transaction_nameと対応するNewRelic::Agent.get_transaction_nameを使用します。

重要

トランザクション名の末尾に角かっこ[suffix]を使用しないでください。 New Relicは、名前から角かっこを自動的に削除します。代わりに、必要に応じて括弧(suffix)またはその他の記号を使用してください。

これは、いくつかの基準をベースにトランザクションをセグメント化する時に便利です。たとえば、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

トランザクションの名前変更は、一部の業務基準をめぐるリクエストのセグメント化にも利用できます。たとえば、次のようなコードを使用することで、トランザクションを「大口顧客」と「小口顧客」にセグメント化できます：

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

トランザクションのエントリーポイントをトレーシングする

通常、エージェントはご利用のアプリケーション内のトランザクションを特定できるものの、対応するフレームワークを使用していないか、エージェントが自動的に記録していないトランザクションを記録したい場合は、メソッドをトランザクションのエントリーポイントとして定義できます：

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

  def transaction
    # execute a transaction
  end
  add_transaction_tracer :transaction
end

クラスメソッドをインストゥルメントするには、クラスシングルトンにメソッドトレーサーを追加します：

class Controller
  include NewRelic::Agent::Instrumentation::ControllerInstrumentation
  
  class << self 
    def transaction
      # execute a transaction
    end
    add_transaction_tracer :transaction
  end
end

Web以外のトランザクションをインストゥルメントする

メソッドレベルのトレーシングに加え、バックグラウンドタスクなどのウェブ以外のトランザクションも、ウェブトランザクションと同レベルのトランザクションおよびエラー詳細でインストゥルメントできます。詳しくはRubyのバックグラウンド処理とデーモンを監視するを参照してください。

高度なカスタムインストゥルメンテーション

エージェントによってトレーシングコードが自動的にインストゥルメントされない場合、通常は標準のメソッドトレーサーで十分です。

ただし、単一のメソッド呼び出しより複雑な処理をインストゥルメントする必要があることもあります。たとえば、メソッド内の数行のコードをインストゥルメントする場合、またはコードのある場所でトランザクションを開始し、別の場所で終了する場合などです。

エージェントバージョン6.0で導入されたTracerモジュールには、トランザクションとセグメントを作成して、現在のトランザクションと対話できる柔軟なAPIが含まれます。

コードのセクションのインストゥルメント

コードのセクションをインストゥルメントするには、コードをブロックでラップし、そのブロックをTracer.in_transactionメソッドに渡します。エージェントはトランザクションが存在することを確認し、その中にブロック内のコード用のセグメントを作成します。

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

トランザクションまたはセグメントの開始

コード内のある場所でトランザクションを開始し、別の場所でトランザクションを終了する必要がある場合 (コールバックベースのイベントで発生する可能性がある)、 NewRelic::Agent::Tracer.start_transaction_or_segmentを呼び出します。 mustこのメソッドの戻り値でfinishを呼び出します。

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

詳しくは、New Relic RubyDocのTracer#start_transaction_または_segmentを参照してください。

スレッドのインストゥルメンテーション

8.7.0以降では、アプリケーションのクラスNewRelic::TracedThreadを使用して、New Relicによってインストゥルメントされたスレッドを作成します。

このクラスをネイティブThreadクラスの代替として使用します。詳細については、TracedThread API のドキュメントを参照してください。