mmtrix_rpm 1.0.0.1

data/lib/mmtrix/agent/instrumentation/controller_instrumentation.rb

@@ -0,0 +1,458 @@
+# encoding: utf-8
+# This file is distributed under Mmtrix's license terms.
+# See https://github.com/mmtrix/rpm/blob/master/LICENSE for complete details.
+
+require 'mmtrix/agent/transaction'
+require 'mmtrix/agent/instrumentation/queue_time'
+require 'mmtrix/agent/instrumentation/ignore_actions'
+module Mmtrix
+  module Agent
+    # @api public
+    module Instrumentation
+      # == Mmtrix instrumentation for controller actions and tasks
+      #
+      # This module can also be used to capture performance information for
+      # background tasks and other non-web transactions, including
+      # detailed transaction traces and traced errors.
+      #
+      # For details on how to instrument background tasks see
+      # {ClassMethods#add_transaction_tracer} and
+      # {#perform_action_with_mmtrix_trace}
+      #
+      # @api public
+      #
+      module ControllerInstrumentation
+
+        def self.included(clazz) # :nodoc:
+          clazz.extend(ClassMethods)
+        end
+
+        # This module is for importing stubs when the agent is disabled
+        module ClassMethodsShim # :nodoc:
+          def mmtrix_ignore(*args); end
+          def mmtrix_ignore_apdex(*args); end
+          def mmtrix_ignore_enduser(*args); end
+        end
+
+        module Shim # :nodoc:
+          def self.included(clazz)
+            clazz.extend(ClassMethodsShim)
+          end
+          def mmtrix_notice_error(*args); end
+          def mmtrix_trace_controller_action(*args); yield; end
+          def perform_action_with_mmtrix_trace(*args); yield; end
+        end
+
+        NR_DO_NOT_TRACE_KEY   = :'@do_not_trace'   unless defined?(NR_DO_NOT_TRACE_KEY  )
+        NR_IGNORE_APDEX_KEY   = :'@ignore_apdex'   unless defined?(NR_IGNORE_APDEX_KEY  )
+        NR_IGNORE_ENDUSER_KEY = :'@ignore_enduser' unless defined?(NR_IGNORE_ENDUSER_KEY)
+        NR_DEFAULT_OPTIONS    = {}.freeze          unless defined?(NR_DEFAULT_OPTIONS   )
+
+        # @api public
+        module ClassMethods
+          # Have Mmtrix ignore actions in this controller.  Specify the actions as hash options
+          # using :except and :only.  If no actions are specified, all actions are ignored.
+          #
+          # @api public
+          #
+          def mmtrix_ignore(specifiers={})
+            mmtrix_ignore_aspect(NR_DO_NOT_TRACE_KEY, specifiers)
+          end
+          # Have Mmtrix omit apdex measurements on the given actions.  Typically used for
+          # actions that are not user facing or that skew your overall apdex measurement.
+          # Accepts :except and :only options, as with #mmtrix_ignore.
+          #
+          # @api public
+          #
+          def mmtrix_ignore_apdex(specifiers={})
+            mmtrix_ignore_aspect(NR_IGNORE_APDEX_KEY, specifiers)
+          end
+
+          # @api public
+          def mmtrix_ignore_enduser(specifiers={})
+            mmtrix_ignore_aspect(NR_IGNORE_ENDUSER_KEY, specifiers)
+          end
+
+          def mmtrix_ignore_aspect(property, specifiers={}) # :nodoc:
+            if specifiers.empty?
+              self.mmtrix_write_attr property, true
+            elsif ! (Hash === specifiers)
+              ::Mmtrix::Agent.logger.error "mmtrix_#{property} takes an optional hash with :only and :except lists of actions (illegal argument type '#{specifiers.class}')"
+            else
+              # symbolize the incoming values
+              specifiers = specifiers.inject({}) do |memo, (key, values)|
+                if values.is_a?(Array)
+                  memo[key] = values.map(&:to_sym)
+                else
+                  memo[key] = values.to_sym
+                end
+                memo
+              end
+              self.mmtrix_write_attr property, specifiers
+            end
+          end
+
+          # Should be monkey patched into the controller class implemented
+          # with the inheritable attribute mechanism.
+          def mmtrix_write_attr(attr_name, value) # :nodoc:
+            instance_variable_set(attr_name, value)
+          end
+
+          def mmtrix_read_attr(attr_name) # :nodoc:
+            instance_variable_get(attr_name)
+          end
+
+          # Add transaction tracing to the given method.  This will treat
+          # the given method as a main entrypoint for instrumentation, just
+          # like controller actions are treated by default.  Useful especially
+          # for background tasks.
+          #
+          # Example for background job:
+          #   class Job
+          #     include Mmtrix::Agent::Instrumentation::ControllerInstrumentation
+          #     def run(task)
+          #        ...
+          #     end
+          #     # Instrument run so tasks show up under task.name.  Note single
+          #     # quoting to defer eval to runtime.
+          #     add_transaction_tracer :run, :name => '#{args[0].name}'
+          #   end
+          #
+          # Here's an example of a controller that uses a dispatcher
+          # action to invoke operations which you want treated as top
+          # level actions, so they aren't all lumped into the invoker
+          # action.
+          #
+          #   MyController < ActionController::Base
+          #     include Mmtrix::Agent::Instrumentation::ControllerInstrumentation
+          #     # dispatch the given op to the method given by the service parameter.
+          #     def invoke_operation
+          #       op = params['operation']
+          #       send op
+          #     end
+          #     # Ignore the invoker to avoid double counting
+          #     mmtrix_ignore :only => 'invoke_operation'
+          #     # Instrument the operations:
+          #     add_transaction_tracer :print
+          #     add_transaction_tracer :show
+          #     add_transaction_tracer :forward
+          #   end
+          #
+          # Here's an example of how to pass contextual information into the transaction
+          # so it will appear in transaction traces:
+          #
+          #   class Job
+          #     include Mmtrix::Agent::Instrumentation::ControllerInstrumentation
+          #     def process(account)
+          #        ...
+          #     end
+          #     # Include the account name in the transaction details.  Note the single
+          #     # quotes to defer eval until call time.
+          #     add_transaction_tracer :process, :params => '{ :account_name => args[0].name }'
+          #   end
+          #
+          # See Mmtrix::Agent::Instrumentation::ControllerInstrumentation#perform_action_with_mmtrix_trace
+          # for the full list of available options.
+          #
+          # @api public
+          #
+          def add_transaction_tracer(method, options={})
+            # The metric path:
+            options[:name] ||= method.to_s
+
+            argument_list = generate_argument_list(options)
+            traced_method, punctuation = parse_punctuation(method)
+            with_method_name, without_method_name = build_method_names(traced_method, punctuation)
+
+            if already_added_transaction_tracer?(self, with_method_name)
+              ::Mmtrix::Agent.logger.warn("Transaction tracer already in place for class = #{self.name}, method = #{method.to_s}, skipping")
+              return
+            end
+
+            class_eval <<-EOC
+              def #{with_method_name}(*args, &block)
+                perform_action_with_mmtrix_trace(#{argument_list.join(',')}) do
+                  #{without_method_name}(*args, &block)
+                 end
+              end
+            EOC
+
+            visibility = Mmtrix::Helper.instance_method_visibility self, method
+
+            alias_method without_method_name, method.to_s
+            alias_method method.to_s, with_method_name
+            send visibility, method
+            send visibility, with_method_name
+            ::Mmtrix::Agent.logger.debug("Traced transaction: class = #{self.name}, method = #{method.to_s}, options = #{options.inspect}")
+          end
+
+          def parse_punctuation(method)
+            [method.to_s.sub(/([?!=])$/, ''), $1]
+          end
+
+          def generate_argument_list(options)
+            options.map do |key, value|
+              value = if value.is_a?(Symbol)
+                value.inspect
+              elsif key == :params
+                value.to_s
+              else
+                %Q["#{value.to_s}"]
+              end
+
+              %Q[:#{key} => #{value}]
+            end
+          end
+
+          def build_method_names(traced_method, punctuation)
+            [ "#{traced_method.to_s}_with_mmtrix_transaction_trace#{punctuation}",
+              "#{traced_method.to_s}_without_mmtrix_transaction_trace#{punctuation}" ]
+          end
+
+          def already_added_transaction_tracer?(target, with_method_name)
+            if Mmtrix::Helper.instance_methods_include?(target, with_method_name)
+              true
+            else
+              false
+            end
+          end
+        end
+
+        # @!parse extend ClassMethods
+
+        class TransactionNamer
+          def self.name_for(txn, traced_obj, category, options={})
+            "#{prefix_for_category(txn, category)}#{path_name(traced_obj, options)}"
+          end
+
+          def self.prefix_for_category(txn, category = nil)
+            category ||= (txn && txn.category)
+            case category
+            when :controller then ::Mmtrix::Agent::Transaction::CONTROLLER_PREFIX
+            when :task       then ::Mmtrix::Agent::Transaction::TASK_PREFIX
+            when :rack       then ::Mmtrix::Agent::Transaction::RACK_PREFIX
+            when :uri        then ::Mmtrix::Agent::Transaction::CONTROLLER_PREFIX
+            when :sinatra    then ::Mmtrix::Agent::Transaction::SINATRA_PREFIX
+            when :middleware then ::Mmtrix::Agent::Transaction::MIDDLEWARE_PREFIX
+            when :grape      then ::Mmtrix::Agent::Transaction::GRAPE_PREFIX
+            else "#{category.to_s}/" # for internal use only
+            end
+          end
+
+          def self.path_name(traced_obj, options={})
+            return options[:path] if options[:path]
+
+            class_name = class_name(traced_obj, options)
+            if options[:name]
+              if class_name
+                "#{class_name}/#{options[:name]}"
+              else
+                options[:name]
+              end
+            elsif traced_obj.respond_to?(:mmtrix_metric_path)
+              traced_obj.mmtrix_metric_path
+            else
+              class_name
+            end
+          end
+
+          def self.class_name(traced_obj, options={})
+            return options[:class_name] if options[:class_name]
+            if (traced_obj.is_a?(Class) || traced_obj.is_a?(Module))
+              traced_obj.name
+            else
+              traced_obj.class.name
+            end
+          end
+        end
+
+        # Yield to the given block with Mmtrix tracing.  Used by
+        # default instrumentation on controller actions in Rails and Merb.
+        # 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
+        # <tt>ClassMethods#add_transaction_tracer</tt>.
+        #
+        # Here's a more verbose version of the example shown in
+        # <tt>ClassMethods#add_transaction_tracer</tt> 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 Mmtrix as if they were first class controller
+        # actions
+        #
+        #   MyController < ActionController::Base
+        #     include Mmtrix::Agent::Instrumentation::ControllerInstrumentation
+        #     # dispatch the given op to the method given by the service parameter.
+        #     def invoke_operation
+        #       op = params['operation']
+        #       perform_action_with_mmtrix_trace(:name => op) do
+        #         send op, params['message']
+        #       end
+        #     end
+        #     # Ignore the invoker to avoid double counting
+        #     mmtrix_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:
+        #
+        # * <tt>:category => :controller</tt> indicates that this is a
+        #   controller action and will appear with all the other actions.  This
+        #   is the default.
+        # * <tt>:category => :task</tt> indicates that this is a
+        #   background task and will show up in Mmtrix with other background
+        #   tasks instead of in the controllers list
+        # * <tt>:category => :middleware</tt> if you are instrumenting a rack
+        #   middleware call.  The <tt>:name</tt> is optional, useful if you
+        #   have more than one potential transaction in the #call.
+        # * <tt>:category => :uri</tt> 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.
+        # * <tt>:name => action_name</tt> is used to specify the action
+        #   name used as part of the metric name
+        # * <tt>:params => {...}</tt> to provide information about the context
+        #   of the call, used in transaction trace display, for example:
+        #   <tt>:params => { :account => @account.name, :file => file.name }</tt>
+        #   These are treated similarly to request parameters in web transactions.
+        #
+        # Seldomly used options:
+        #
+        # * <tt>:class_name => aClass.name</tt> is used to override the name
+        #   of the class when used inside the metric name.  Default is the
+        #   current class.
+        # * <tt>:path => metric_path</tt> is *deprecated* in the public API.  It
+        #   allows you to set the entire metric after the category part.  Overrides
+        #   all the other options.
+        # * <tt>:request => Rack::Request#new(env)</tt> is used to pass in a
+        #   request object that may respond to path and referer.
+        #
+        # @api public
+        #
+        def perform_action_with_mmtrix_trace(*args, &block) #THREAD_LOCAL_ACCESS
+          state = Mmtrix::Agent::TransactionState.tl_get
+          state.request = mmtrix_request(args)
+
+          skip_tracing = do_not_trace? || !state.is_execution_traced?
+
+          if skip_tracing
+            state.current_transaction.ignore! if state.current_transaction
+            Mmtrix::Agent.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 : NR_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
+              Mmtrix::Agent.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
+
+        protected
+
+        def mmtrix_request(args)
+          opts = args.first
+          # passed as a parameter to add_transaction_tracer
+          if opts.respond_to?(:keys) && opts.respond_to?(:[]) && opts[:request]
+            opts[:request]
+          # in a Rails app
+          elsif self.respond_to?(:request)
+            self.request
+          end
+        end
+
+        # Should be implemented in the dispatcher class
+        def mmtrix_response_code; end
+
+        def mmtrix_request_headers(state)
+          request = state.request
+          if request
+            if request.respond_to?(:headers)
+              request.headers
+            elsif request.respond_to?(:env)
+              request.env
+            end
+          end
+        end
+
+        # overrideable method to determine whether to trace an action
+        # or not - you may override this in your controller and supply
+        # your own logic for ignoring transactions.
+        def do_not_trace?
+          _is_filtered?(NR_DO_NOT_TRACE_KEY)
+        end
+
+        # overrideable method to determine whether to trace an action
+        # for purposes of apdex measurement - you can use this to
+        # ignore things like api calls or other fast non-user-facing
+        # actions
+        def ignore_apdex?
+          _is_filtered?(NR_IGNORE_APDEX_KEY)
+        end
+
+        def ignore_enduser?
+          _is_filtered?(NR_IGNORE_ENDUSER_KEY)
+        end
+
+        private
+
+        def create_transaction_options(trace_options, category, state)
+          txn_options = {}
+          txn_options[:request]   = trace_options[:request]
+          txn_options[:request] ||= request if respond_to?(:request)
+          # params should have been filtered before calling perform_action_with_mmtrix_trace
+          txn_options[:filtered_params] = trace_options[:params]
+          txn_options[:transaction_name] = TransactionNamer.name_for(nil, self, category, trace_options)
+          txn_options[:apdex_start_time] = detect_queue_start_time(state)
+          txn_options
+        end
+
+        # Filter out a request if it matches one of our parameters for
+        # ignoring it - the key is either NR_DO_NOT_TRACE_KEY or NR_IGNORE_APDEX_KEY
+        def _is_filtered?(key)
+          name = if respond_to?(:action_name)
+            action_name
+          else
+            :'[action_name_missing]'
+          end
+
+          Mmtrix::Agent::Instrumentation::IgnoreActions.is_filtered?(
+            key,
+            self.class,
+            name)
+        end
+
+        def detect_queue_start_time(state)
+          headers = mmtrix_request_headers(state)
+
+          QueueTime.parse_frontend_timestamp(headers) if headers
+        end
+      end
+    end
+  end
+end

data/lib/mmtrix/agent/instrumentation/curb.rb

@@ -0,0 +1,191 @@
+# encoding: utf-8
+# This file is distributed under Mmtrix's license terms.
+# See https://github.com/mmtrix/rpm/blob/master/LICENSE for complete details.
+
+DependencyDetection.defer do
+  named :curb
+
+  CURB_MIN_VERSION = ::Mmtrix::VersionNumber.new("0.8.1")
+
+  depends_on do
+    defined?(::Curl) && defined?(::Curl::CURB_VERSION) &&
+      ::Mmtrix::VersionNumber.new(::Curl::CURB_VERSION) >= CURB_MIN_VERSION
+  end
+
+  executes do
+    ::Mmtrix::Agent.logger.info 'Installing Curb instrumentation'
+    require 'mmtrix/agent/cross_app_tracing'
+    require 'mmtrix/agent/http_clients/curb_wrappers'
+  end
+
+  executes do
+    class Curl::Easy
+
+      attr_accessor :_nr_instrumented,
+                    :_nr_http_verb,
+                    :_nr_header_str,
+                    :_nr_original_on_header,
+                    :_nr_original_on_complete,
+                    :_nr_serial
+
+      # We have to hook these three methods separately, as they don't use
+      # Curl::Easy#http
+      def http_head_with_mmtrix(*args, &blk)
+        self._nr_http_verb = :HEAD
+        http_head_without_mmtrix(*args, &blk)
+      end
+      alias_method :http_head_without_mmtrix, :http_head
+      alias_method :http_head, :http_head_with_mmtrix
+
+      def http_post_with_mmtrix(*args, &blk)
+        self._nr_http_verb = :POST
+        http_post_without_mmtrix(*args, &blk)
+      end
+      alias_method :http_post_without_mmtrix, :http_post
+      alias_method :http_post, :http_post_with_mmtrix
+
+      def http_put_with_mmtrix(*args, &blk)
+        self._nr_http_verb = :PUT
+        http_put_without_mmtrix(*args, &blk)
+      end
+      alias_method :http_put_without_mmtrix, :http_put
+      alias_method :http_put, :http_put_with_mmtrix
+
+
+      # Hook the #http method to set the verb.
+      def http_with_mmtrix( verb )
+        self._nr_http_verb = verb.to_s.upcase
+        http_without_mmtrix( verb )
+      end
+
+      alias_method :http_without_mmtrix, :http
+      alias_method :http, :http_with_mmtrix
+
+
+      # Hook the #perform method to mark the request as non-parallel.
+      def perform_with_mmtrix
+        self._nr_serial = true
+        perform_without_mmtrix
+      end
+
+      alias_method :perform_without_mmtrix, :perform
+      alias_method :perform, :perform_with_mmtrix
+
+      # We override this method in order to ensure access to header_str even
+      # though we use an on_header callback
+      def header_str_with_mmtrix
+        if self._nr_serial
+          self._nr_header_str
+        else
+          # Since we didn't install a header callback for a non-serial request,
+          # just fall back to the original implementation.
+          header_str_without_mmtrix
+        end
+      end
+
+      alias_method :header_str_without_mmtrix, :header_str
+      alias_method :header_str, :header_str_with_mmtrix
+    end # class Curl::Easy
+
+
+    class Curl::Multi
+      include Mmtrix::Agent::MethodTracer
+
+      # Add CAT with callbacks if the request is serial
+      def add_with_mmtrix(curl) #THREAD_LOCAL_ACCESS
+        if curl.respond_to?(:_nr_serial) && curl._nr_serial
+          hook_pending_request(curl) if Mmtrix::Agent.tl_is_execution_traced?
+        end
+
+        return add_without_mmtrix( curl )
+      end
+
+      alias_method :add_without_mmtrix, :add
+      alias_method :add, :add_with_mmtrix
+
+
+      # Trace as an External/Multiple call if the first request isn't serial.
+      def perform_with_mmtrix(&blk)
+        return perform_without_mmtrix if
+          self.requests.first &&
+          self.requests.first.respond_to?(:_nr_serial) &&
+          self.requests.first._nr_serial
+
+        trace_execution_scoped("External/Multiple/Curb::Multi/perform") do
+          perform_without_mmtrix(&blk)
+        end
+      end
+
+      alias_method :perform_without_mmtrix, :perform
+      alias_method :perform, :perform_with_mmtrix
+
+
+      # Instrument the specified +request+ (a Curl::Easy object) and set up cross-application
+      # tracing if it's enabled.
+      def hook_pending_request(request) #THREAD_LOCAL_ACCESS
+        wrapped_request, wrapped_response = wrap_request(request)
+        state = Mmtrix::Agent::TransactionState.tl_get
+        t0    = Time.now
+        node  = Mmtrix::Agent::CrossAppTracing.start_trace(state, t0, wrapped_request)
+
+        unless request._nr_instrumented
+          install_header_callback(request, wrapped_response)
+          install_completion_callback(request, t0, node, wrapped_request, wrapped_response)
+          request._nr_instrumented = true
+        end
+      rescue => err
+        Mmtrix::Agent.logger.error("Untrapped exception", err)
+      end
+
+
+      # Create request and response adapter objects for the specified +request+
+      def wrap_request(request)
+        return Mmtrix::Agent::HTTPClients::CurbRequest.new(request),
+               Mmtrix::Agent::HTTPClients::CurbResponse.new(request)
+      end
+
+
+      # Install a callback that will record the response headers to enable
+      # CAT linking
+      def install_header_callback( request, wrapped_response )
+        original_callback = request.on_header
+        request._nr_original_on_header = original_callback
+        request._nr_header_str = ''
+        request.on_header do |header_data|
+          wrapped_response.append_header_data( header_data )
+
+          if original_callback
+            original_callback.call( header_data )
+          else
+            header_data.length
+          end
+        end
+      end
+
+      # Install a callback that will finish the trace.
+      def install_completion_callback(request, t0, node, wrapped_request, wrapped_response) #THREAD_LOCAL_ACCESS
+        original_callback = request.on_complete
+        request._nr_original_on_complete = original_callback
+        request.on_complete do |finished_request|
+          begin
+            state = Mmtrix::Agent::TransactionState.tl_get
+            Mmtrix::Agent::CrossAppTracing.finish_trace(state, t0, node, wrapped_request, wrapped_response)
+          ensure
+            # Make sure the existing completion callback is run, and restore the
+            # on_complete callback to how it was before.
+            original_callback.call(finished_request) if original_callback
+            remove_instrumentation_callbacks(request)
+          end
+        end
+      end
+
+      def remove_instrumentation_callbacks(request)
+        request.on_complete(&request._nr_original_on_complete)
+        request.on_header(&request._nr_original_on_header)
+        request._nr_instrumented = false
+      end
+
+    end # class Curl::Multi
+
+  end
+end