oneapm_rpm 1.1.0

data/lib/one_apm/inst/rails_middleware.rb

@@ -0,0 +1,40 @@
+# encoding: utf-8
+
+require 'one_apm/rack/middleware_wrapper'
+
+LibraryDetection.defer do
+  named :rails_middleware
+
+  depends_on do
+    defined?(::Rails) && ::Rails::VERSION::MAJOR.to_i >= 3
+  end
+
+  depends_on do
+    !::OneApm::Agent.config[:disable_rack_middleware]
+  end
+
+  executes do
+    ::OneApm::Agent.logger.info("Installing Rails 3+ middleware instrumentation")
+
+    module ActionDispatch
+      class MiddlewareStack
+        class Middleware
+
+          def build_with_one_apm(app)
+            # MiddlewareWrapper.wrap guards against double-wrapping here.
+            # We need to instrument the innermost app (usually a RouteSet),
+            # which will never itself be the return value from #build, but will
+            # instead be the initial value of the app argument.
+            wrapped_app = ::OneApm::Rack::MiddlewareWrapper.wrap(app)
+            result = build_without_one_apm(wrapped_app)
+            ::OneApm::Rack::MiddlewareWrapper.wrap(result)
+          end
+
+          alias_method :build_without_one_apm, :build
+          alias_method :build, :build_with_one_apm
+        end
+      end
+    end
+
+  end
+end

data/lib/one_apm/inst/support/evented_subscriber.rb

@@ -0,0 +1,98 @@
+# encoding: utf-8
+
+module OneApm
+  module Agent
+    module Instrumentation
+      class EventedSubscriber
+        def initialize
+          @queue_key = ['OneApm', self.class.name, object_id].join('-')
+        end
+
+        def self.subscribed?
+          # TODO: need to talk to Rails core about an API for this,
+          # rather than digging through Listener ivars
+          ActiveSupport::Notifications.notifier.instance_variable_get(:@subscribers) \
+            .find{|s| s.instance_variable_get(:@delegate).class == self }
+        end
+
+        def self.subscribe(pattern)
+          if !subscribed?
+            ActiveSupport::Notifications.subscribe(pattern, new)
+          end
+        end
+
+        def start(name, id, payload)
+          event = ActiveSupport::Notifications::Event.new(name, Time.now, nil, id, payload)
+          push_event(event)
+          return event
+        end
+
+        def finish(name, id, payload)
+          pop_event(id)
+        end
+
+        def log_notification_error(error, name, event_type)
+          # These are important enough failures that we want the backtraces
+          # logged at error level, hence the explicit log_exception call.
+          OneApm::Agent.logger.error("Error during #{event_type} callback for event '#{name}':")
+          OneApm::Agent.logger.log_exception(:error, error)
+        end
+
+        def push_event(event)
+          parent = event_stack[event.transaction_id].last
+          if parent && event.respond_to?(:parent=)
+            event.parent = parent
+            parent << event
+          end
+          event_stack[event.transaction_id].push event
+        end
+
+        def pop_event(transaction_id)
+          event = event_stack[transaction_id].pop
+          event.end = Time.now
+          return event
+        end
+
+        def event_stack
+          Thread.current[@queue_key] ||= Hash.new {|h,id| h[id] = [] }
+        end
+      end
+
+      # Taken from ActiveSupport::Notifications::Event, pasted here
+      # with a couple minor additions so we don't have a hard
+      # dependency on ActiveSupport::Notifications.
+      #
+      # Represents an intrumentation event, provides timing and metric
+      # name information useful when recording metrics.
+      class Event
+        attr_reader :name, :time, :transaction_id, :payload, :children
+        attr_accessor :end, :parent, :frame
+
+        def initialize(name, start, ending, transaction_id, payload)
+          @name           = name
+          @payload        = payload.dup
+          @time           = start
+          @transaction_id = transaction_id
+          @end            = ending
+          @children       = []
+        end
+
+        def metric_name
+          raise NotImplementedError
+        end
+
+        def duration
+          self.end - time
+        end
+
+        def <<(event)
+          @children << event
+        end
+
+        def parent_of?(event)
+          @children.include? event
+        end
+      end
+    end
+  end
+end

data/lib/one_apm/inst/support/ignore_actions.rb

@@ -0,0 +1,39 @@
+# encoding: utf-8
+
+module OneApm
+  module Agent
+    module Instrumentation
+      module IgnoreActions
+        def self.is_filtered?(key, klass, action_name)
+          # We'll walk the superclass chain and see if
+          # any class says 'yes, filter this one'.
+
+          while klass.respond_to? :oneapm_read_attr
+            ignore_actions = klass.oneapm_read_attr(key)
+
+            should_filter = case ignore_actions
+            when Hash
+              only_actions   = Array(ignore_actions[:only])
+              except_actions = Array(ignore_actions[:except])
+              action_name    = action_name.to_sym
+
+              only_actions.include?(action_name) || (!except_actions.empty? && !except_actions.include?(action_name))
+            else
+              !!ignore_actions
+            end
+
+            return true if should_filter
+
+            # Nothing so far says we should filter,
+            # so keep checking up the superclass chain.
+            klass = klass.superclass
+          end
+
+          # Getting here means that no class filtered this.
+          false
+        end
+      end
+    end
+  end
+end
+

data/lib/one_apm/inst/support/queue_time.rb

@@ -0,0 +1,76 @@
+# encoding: utf-8
+
+module OneApm
+  module Agent
+    module Instrumentation
+      # https://oneapm.com/docs/features/tracking-front-end-time
+      # Record queue time metrics based on any of three headers
+      # which can be set on the request.
+      module QueueTime
+        unless defined?(REQUEST_START_HEADER)
+          REQUEST_START_HEADER    = 'HTTP_X_REQUEST_START'.freeze
+          QUEUE_START_HEADER      = 'HTTP_X_QUEUE_START'.freeze
+          MIDDLEWARE_START_HEADER = 'HTTP_X_MIDDLEWARE_START'.freeze
+          ALL_QUEUE_METRIC        = 'WebFrontend/QueueTime'.freeze
+          # any timestamps before this are thrown out and the parser
+          # will try again with a larger unit (2000/1/1 UTC)
+          EARLIEST_ACCEPTABLE_TIME = Time.at(946684800)
+
+          CANDIDATE_HEADERS = [
+            REQUEST_START_HEADER,
+            QUEUE_START_HEADER,
+            MIDDLEWARE_START_HEADER
+          ].freeze
+
+          DIVISORS = [1_000_000, 1_000, 1]
+        end
+
+        module_function
+
+        def parse_frontend_timestamp(headers, now=Time.now)
+          earliest = nil
+
+          CANDIDATE_HEADERS.each do |header|
+            if headers[header]
+              parsed = parse_timestamp(timestamp_string_from_header_value(headers[header]))
+              if parsed && (!earliest || parsed < earliest)
+                earliest = parsed
+              end
+            end
+          end
+
+          if earliest && earliest > now
+            OneApm::Agent.logger.debug("Negative queue time detected, treating as zero: start=#{earliest.to_f} > now=#{now.to_f}")
+            earliest = now
+          end
+
+          earliest
+        end
+
+        def timestamp_string_from_header_value(value)
+          case value
+          when /^\s*([\d+\.]+)\s*$/ then $1
+          # following regexp intentionally unanchored to handle
+          # (ie ignore) leading server names
+          when /t=([\d+\.]+)/       then $1
+          end
+        end
+
+        def parse_timestamp(string)
+          DIVISORS.each do |divisor|
+            begin
+              t = Time.at(string.to_f / divisor)
+              return t if t > EARLIEST_ACCEPTABLE_TIME
+            rescue RangeError
+              # On Ruby versions built with a 32-bit time_t, attempting to
+              # instantiate a Time object in the far future raises a RangeError,
+              # in which case we know we've chosen the wrong divisor.
+            end
+          end
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/one_apm/inst/transaction_base.rb

@@ -0,0 +1,405 @@
+# encoding: utf-8
+
+require 'one_apm/transaction'
+require 'one_apm/transaction/transaction_namer'
+require 'one_apm/inst/support/queue_time'
+require 'one_apm/inst/support/ignore_actions'
+
+module OneApm
+  module Agent
+    module Instrumentation
+      #
+      # OneApm instrumentation for transactions
+      #
+      # * controller actions
+      # * background tasks
+      # * external web calls
+      #
+      # see
+      #  * add_transaction_tracer
+      #  * perform_action_with_oneapm_trace
+      #
+      module TransactionBase
+
+        def self.included(clazz)
+          clazz.extend(ClassMethods)
+        end
+
+        module Shim
+          module ClassMethodsShim
+            def oneapm_ignore(*args); end
+            def oneapm_ignore_apdex(*args); end
+            def oneapm_ignore_enduser(*args); end
+          end
+
+          def self.included(clazz)
+            clazz.extend(ClassMethodsShim)
+          end
+          def oneapm_notice_error(*args); end
+          def one_apm_trace_controller_action(*args); yield; end
+          def perform_action_with_oneapm_trace(*args); yield; end
+        end
+
+        OA_DO_NOT_TRACE_KEY   = :'@do_not_trace'   unless defined?(OA_DO_NOT_TRACE_KEY  )
+        OA_IGNORE_APDEX_KEY   = :'@ignore_apdex'   unless defined?(OA_IGNORE_APDEX_KEY  )
+        OA_IGNORE_ENDUSER_KEY = :'@ignore_enduser' unless defined?(OA_IGNORE_ENDUSER_KEY)
+        OA_DEFAULT_OPTIONS    = {}.freeze          unless defined?(OA_DEFAULT_OPTIONS   )
+
+        module ClassMethods
+
+          # Have OneApm 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 oneapm_ignore(options = {})
+            oneapm_ignore_aspect(OA_DO_NOT_TRACE_KEY, options)
+          end
+
+          # Have OneApm 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.
+          #
+          # @api public
+          #
+          def oneapm_ignore_apdex(options = {})
+            oneapm_ignore_aspect(OA_IGNORE_APDEX_KEY, options)
+          end
+
+          # Have OneApm skip install javascript_instrumentation
+          #
+          # @api public
+          #
+          def oneapm_ignore_enduser(options = {})
+            oneapm_ignore_aspect(OA_IGNORE_ENDUSER_KEY, options)
+          end
+
+          def oneapm_ignore_aspect(property, options = {})
+            if options.empty?
+              oneapm_write_attr property, true
+            elsif !options.is_a?(Hash)
+              ::OneApm::Agent.logger.error "oneapm_#{property} takes an optional hash with :only and :except lists of actions (illegal argument type '#{options.class}')"
+            else
+              oneapm_write_attr property, options
+            end
+          end
+
+          def oneapm_write_attr(attr_name, value)
+            instance_variable_set(attr_name, value)
+          end
+
+          def oneapm_read_attr(attr_name)
+            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 OneApm::Agent::Instrumentation::TransactionBase
+          #     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 OneApm::Agent::Instrumentation::TransactionBase
+          #     # 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
+          #     oneapm_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 OneApm::Agent::Instrumentation::TransactionBase
+          #     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 OneApm::Agent::Instrumentation::TransactionBase#perform_action_with_oneapm_trace
+          # for the full list of available options.
+          #
+          # @api public
+          #
+          def add_transaction_tracer(method, options = {})
+            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)
+              ::OneApm::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_oneapm_trace(#{argument_list.join(',')}) do
+                  #{without_method_name}(*args, &block)
+                end
+              end
+            EOC
+
+            visibility = OneApm::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
+
+            ::OneApm::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_oneapm_transaction_trace#{punctuation}",
+              "#{traced_method.to_s}_without_oneapm_transaction_trace#{punctuation}"
+              ]
+          end
+
+          def already_added_transaction_tracer?(target, with_method_name)
+            if OneApm::Helper.instance_methods_include?(target, with_method_name)
+              true
+            else
+              false
+            end
+          end
+        end
+
+        # 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
+        # <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 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:
+        #
+        # * <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 OneApm 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 uri and referer.
+        #
+        # @api public
+        #
+        def perform_action_with_oneapm_trace(*args, &block) #THREAD_LOCAL_ACCESS
+          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::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 : 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::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 oneapm_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 oneapm_response_code; end
+
+        def oneapm_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?(OA_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?(OA_IGNORE_APDEX_KEY)
+        end
+
+        def ignore_enduser?
+          _is_filtered?(OA_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_oneapm_trace
+          txn_options[:filtered_params] = trace_options[:params]
+          txn_options[:transaction_name] = OneApm::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 OA_DO_NOT_TRACE_KEY or OA_IGNORE_APDEX_KEY
+        def _is_filtered?(key)
+          name = if respond_to?(:action_name)
+            action_name
+          else
+            :'[action_name_missing]'
+          end
+
+          OneApm::Agent::Instrumentation::IgnoreActions.is_filtered?(
+            key,
+            self.class,
+            name)
+        end
+
+        def detect_queue_start_time(state)
+          headers = oneapm_request_headers(state)
+
+          QueueTime.parse_frontend_timestamp(headers) if headers
+        end
+      end
+    end
+  end
+end