Module: OneApm::Agent::Instrumentation::TransactionBase

Included in:
Rack, Sinatra
Defined in:
lib/one_apm/inst/transaction_base.rb

Overview

OneApm instrumentation for transactions

  • controller actions

  • background tasks

  • external web calls

see

* add_transaction_tracer
* perform_action_with_oneapm_trace

Defined Under Namespace

Modules: ClassMethods, Shim

Constant Summary collapse

OA_DO_NOT_TRACE_KEY = 
:'@do_not_trace'
OA_IGNORE_APDEX_KEY = 
:'@ignore_apdex'
OA_IGNORE_ENDUSER_KEY = 
:'@ignore_enduser'
OA_DEFAULT_OPTIONS = 
{}.freeze

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(clazz) ⇒ Object 



24
25
26
 
# File 'lib/one_apm/inst/transaction_base.rb', line 24

def self.included(clazz)
  clazz.extend(ClassMethods)
end

Instance Method Details

#perform_action_with_oneapm_trace(*args, &block) ⇒ Object

Yield to the given block with OneApm tracing. Used by default instrumentation on controller actions in Rails. But it can also be used in custom instrumentation of controller methods and background tasks.

This is the method invoked by instrumentation added by the ClassMethods#add_transaction_tracer.

Here’s a more verbose version of the example shown in ClassMethods#add_transaction_tracer using this method instead of #add_transaction_tracer.

Below is a controller with an invoke_operation action which dispatches to more specific operation methods based on a parameter (very dangerous, btw!). With this instrumentation, the invoke_operation action is ignored but the operation methods show up in OneApm as if they were first class controller actions

MyController < ActionController::Base
  include OneApm::Agent::Instrumentation::TransactionBase
  # dispatch the given op to the method given by the service parameter.
  def invoke_operation
    op = params['operation']
    perform_action_with_oneapm_trace(:name => op) do
      send op, params['message']
    end
  end
  # Ignore the invoker to avoid double counting
  oneapm_ignore :only => 'invoke_operation'
end

When invoking this method explicitly as in the example above, pass in a block to measure with some combination of options:

  • :category => :controller indicates that this is a controller action and will appear with all the other actions. This is the default.

  • :category => :task indicates that this is a background task and will show up in OneApm with other background tasks instead of in the controllers list

  • :category => :middleware if you are instrumenting a rack middleware call. The :name is optional, useful if you have more than one potential transaction in the #call.

  • :category => :uri indicates that this is a web transaction whose name is a normalized URI, where ‘normalized’ means the URI does not have any elements with data in them such as in many REST URIs.

  • :name => action_name is used to specify the action name used as part of the metric name

  • :params => {...} to provide information about the context of the call, used in transaction trace display, for example: :params => { :account => @account.name, :file => file.name } These are treated similarly to request parameters in web transactions.

Seldomly used options:

  • :class_name => aClass.name is used to override the name of the class when used inside the metric name. Default is the current class.

  • :path => metric_path is deprecated in the public API. It allows you to set the entire metric after the category part. Overrides all the other options.

  • :request => Rack::Request#new(env) is used to pass in a request object that may respond to uri and referer.



285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
 
# File 'lib/one_apm/inst/transaction_base.rb', line 285

def perform_action_with_oneapm_trace(*args, &block)
  state = OneApm::TransactionState.tl_get
  state.request = oneapm_request(args)

  skip_tracing = do_not_trace? || !state.is_execution_traced?

  if skip_tracing
    state.current_transaction.ignore! if state.current_transaction
    OneApm::Manager.disable_all_tracing { return yield }
  end

  # This method has traditionally taken a variable number of arguments, but the
  # only one that is expected / used is a single options hash.  We are preserving
  # the *args method signature to ensure backwards compatibility.

  trace_options = args.last.is_a?(Hash) ? args.last : OA_DEFAULT_OPTIONS
  category      = trace_options[:category] || :controller
  txn_options   = create_transaction_options(trace_options, category, state)
  begin
    txn = Transaction.start(state, category, txn_options)

    begin
      yield
    rescue => e
      OneApm::Manager.notice_error(e)
      raise
    end

  ensure
    if txn
      txn.ignore_apdex!   if ignore_apdex?
      txn.ignore_enduser! if ignore_enduser?
    end
    Transaction.stop(state)
  end
end