appoptics_apm 4.0.2

data/lib/appoptics_apm/api/logging.rb

@@ -0,0 +1,359 @@
+#--
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+#++
+
+# Make sure Set is loaded if possible.
+begin
+  require 'set'
+rescue LoadError
+  class Set; end # :nodoc:
+end
+
+
+module AppOpticsAPM
+  module API
+    ##
+    # This modules provides the X-Trace logging facilities.
+    #
+    # These are the lower level methods, please see AppOpticsAPM::API::Tracing
+    # for the higher level methods
+    module Logging
+      @@ints_or_nil = [Integer, Float, NilClass, String]
+      @@ints_or_nil << Fixnum unless RUBY_VERSION >= '2.4'
+
+      ##
+      # Public: Report an event in an active trace.
+      #
+      # ==== Arguments
+      #
+      # * +layer+ - The layer the reported event belongs to
+      # * +label+ - The label for the reported event. See SDK documentation for reserved labels and usage.
+      # * +opts+  - A hash containing key/value pairs that will be reported along with this event (optional).
+      # * +event+ - An event to be used instead of generating a new one (see also start_trace_with_target)
+      #
+      # ==== Example
+      #
+      #   AppOpticsAPM::API.log('logical_layer', 'entry')
+      #   AppOpticsAPM::API.log('logical_layer', 'info', { :list_length => 20 })
+      #   AppOpticsAPM::API.log('logical_layer', 'exit')
+      #
+      # Returns nothing.
+      def log(layer, label, opts = {}, event=nil)
+        return if !AppOpticsAPM.tracing?
+
+        event ||= AppOpticsAPM::Context.createEvent
+        log_event(layer, label, event, opts)
+      end
+
+      ##
+      # Public: Report an exception.
+      #
+      # ==== Arguments
+      #
+      # * +layer+ - The layer the reported event belongs to
+      # * +exn+ - The exception to report
+      # * +opts+ - Custom params if you want to log extra information
+      #
+      # ==== Example
+      #
+      #   begin
+      #     my_iffy_method
+      #   rescue Exception => e
+      #     AppOpticsAPM::API.log_exception('rails', e, { user: user_id })
+      #     raise
+      #   end
+      #
+      # Returns nothing.
+      def log_exception(layer, exn, opts = {})
+        return if !AppOpticsAPM.tracing? || exn.instance_variable_get(:@oboe_logged)
+
+        unless exn
+          AppOpticsAPM.logger.debug '[appoptics_apm/debug] log_exception called with nil exception'
+          return
+        end
+
+        opts.merge!(:ErrorClass => exn.class.name,
+                    :ErrorMsg => exn.message,
+                    :Backtrace => exn.backtrace.join("\r\n")) if exn.backtrace
+
+        exn.instance_variable_set(:@oboe_logged, true)
+        log(layer, :error, opts)
+      end
+
+      ##
+      # Public: Decide whether or not to start a trace, and report an entry event
+      # appropriately.
+      #
+      # ==== Attributes
+      #
+      # * +layer+ - The layer the reported event belongs to
+      # * +xtrace+ - An xtrace metadata string, or nil.  Used for cross-application tracing.
+      # * +opts+ - A hash containing key/value pairs that will be reported along with this event (optional).
+      #
+      # ==== Example
+      #
+      #   AppOpticsAPM::API.log_start(:layer_name, nil, { :id => @user.id })
+      #
+      # Returns an xtrace metadata string
+      def log_start(layer, xtrace = nil, opts = {})
+        return if !AppOpticsAPM.loaded || (opts.key?(:URL) && ::AppOpticsAPM::Util.static_asset?(opts[:URL]))
+
+        #--
+        # Is the below necessary? Only on JRuby? Could there be an existing context but not x-trace header?
+        # See discussion at:
+        # https://github.com/librato/ruby-tracelytics/pull/6/files?diff=split#r131029135
+        #
+        # Used by JRuby/Java webservers such as Tomcat
+        # AppOpticsAPM::Context.fromString(xtrace) if AppOpticsAPM.pickup_context?(xtrace)
+
+        # if AppOpticsAPM.tracing?
+        #   # Pre-existing context.  Either we inherited context from an
+        #   # incoming X-Trace request header or under JRuby, Joboe started
+        #   # tracing before the JRuby code was called (e.g. Tomcat)
+        #   AppOpticsAPM.is_continued_trace = true
+
+        #   if AppOpticsAPM.has_xtrace_header
+        #     opts[:TraceOrigin] = :continued_header
+        #   elsif AppOpticsAPM.has_incoming_context
+        #     opts[:TraceOrigin] = :continued_context
+        #   else
+        #     opts[:TraceOrigin] = :continued
+        #   end
+
+        # return log_entry(layer, opts)
+        # end
+        #++
+
+        if AppOpticsAPM.sample?(opts.merge(:layer => layer, :xtrace => xtrace))
+          # Yes, we're sampling this request
+          # Probablistic tracing of a subset of requests based off of
+          # sample rate and sample source
+          opts[:SampleRate]        = AppOpticsAPM.sample_rate
+          opts[:SampleSource]      = AppOpticsAPM.sample_source
+          opts[:TraceOrigin]       = :always_sampled
+
+          if xtrace_v2?(xtrace)
+            # continue valid incoming xtrace
+            # use it for current context, ensuring sample bit is set
+            AppOpticsAPM::XTrace.set_sampled(xtrace)
+
+            md = AppOpticsAPM::Metadata.fromString(xtrace)
+            AppOpticsAPM::Context.fromString(xtrace)
+            log_event(layer, :entry, md.createEvent, opts)
+          else
+            # discard invalid incoming xtrace
+            # create a new context, ensuring sample bit set
+            md = AppOpticsAPM::Metadata.makeRandom(true)
+            AppOpticsAPM::Context.set(md)
+            log_event(layer, :entry, AppOpticsAPM::Event.startTrace(md), opts)
+          end
+        else
+          # No, we're not sampling this request
+          # set the context but don't log the event
+          if xtrace_v2?(xtrace)
+            # continue valid incoming xtrace
+            # use it for current context, ensuring sample bit is not set
+            AppOpticsAPM::XTrace.unset_sampled(xtrace)
+            AppOpticsAPM::Context.fromString(xtrace)
+          else
+            # discard invalid incoming xtrace
+            # create a new context, ensuring sample bit not set
+            md = AppOpticsAPM::Metadata.makeRandom(false)
+            AppOpticsAPM::Context.fromString(md.toString)
+          end
+        end
+        AppOpticsAPM::Context.toString
+      end
+
+      ##
+      # Public: Report an exit event and potentially clear the tracing context.
+      #
+      # ==== Attributes
+      #
+      # * +layer+ - The layer the reported event belongs to
+      # * +opts+ - A hash containing key/value pairs that will be reported along with this event (optional).
+      #
+      # ==== Example
+      #
+      #   AppOpticsAPM::API.log_end(:layer_name, { :id => @user.id })
+      #
+      # Returns an xtrace metadata string
+      def log_end(layer, opts = {})
+        return unless AppOpticsAPM.tracing?
+
+        log_event(layer, :exit, AppOpticsAPM::Context.createEvent, opts)
+        AppOpticsAPM::Context.toString
+      ensure
+        AppOpticsAPM::Context.clear unless AppOpticsAPM.has_incoming_context?
+      end
+
+      ##
+      # Public: Log an entry event
+      #
+      # A helper method to create and log an entry event
+      #
+      # ==== Attributes
+      #
+      # * +layer+ - The layer the reported event belongs to
+      # * +kvs+ - A hash containing key/value pairs that will be reported along with this event (optional).
+      # * +op+ - To identify the current operation being traced.  Used to avoid double tracing recursive calls.
+      #
+      # ==== Example
+      #
+      #   AppOpticsAPM::API.log_entry(:layer_name, { :id => @user.id })
+      #
+      # Returns an xtrace metadata string
+      def log_entry(layer, opts = {}, op = nil)
+        return unless AppOpticsAPM.tracing?
+
+        AppOpticsAPM.layer_op = op.to_sym if op
+        log_event(layer, :entry, AppOpticsAPM::Context.createEvent, opts)
+      end
+
+      ##
+      # Public: Log an info event
+      #
+      # A helper method to create and log an info event
+      #
+      # ==== Attributes
+      #
+      # * +layer+ - The layer the reported event belongs to
+      # * +opts+ - A hash containing key/value pairs that will be reported along with this event (optional).
+      #
+      # ==== Example
+      #
+      #   AppOpticsAPM::API.log_info(:layer_name, { :id => @user.id })
+      #
+      # Returns an xtrace metadata string
+      def log_info(layer, kvs = {})
+        return unless AppOpticsAPM.tracing?
+
+        log_event(layer, :info, AppOpticsAPM::Context.createEvent, kvs)
+      end
+
+      ##
+      # Public: Log an exit event
+      #
+      # A helper method to create and log an exit event
+      #
+      # ==== Attributes
+      #
+      # * +layer+ - The layer the reported event belongs to
+      # * +opts+ - A hash containing key/value pairs that will be reported along with this event (optional).
+      # * +_op+ - deprecated, has been used to avoid double tracing recursive calls, but is irrelevant in +log_exit+
+      #
+      # ==== Example
+      #
+      #   AppOpticsAPM::API.log_exit(:layer_name, { :id => @user.id })
+      #
+      # Returns an xtrace metadata string (TODO: does it?)
+      def log_exit(layer, opts = {}, _op = nil)
+        return unless AppOpticsAPM.tracing?
+
+        AppOpticsAPM.layer_op = nil
+        log_event(layer, :exit, AppOpticsAPM::Context.createEvent, opts)
+      end
+
+      ##
+      # Public: Log an exit event from multiple requests
+      #
+      # A helper method to create and log an info event
+      # If we return from a request that faned out multiple requests
+      # we can add the collected X-Traces to the exit event
+      #
+      # ==== Attributes
+      #
+      # * +layer+ - The layer the reported event belongs to
+      # * +traces+ - An array with X-Trace strings returned from the requests
+      #
+      def log_multi_exit(layer, traces)
+        return unless AppOpticsAPM.tracing?
+        task_id = AppOpticsAPM::XTrace.task_id(AppOpticsAPM::Context.toString)
+        event = AppOpticsAPM::Context.createEvent
+        traces.each do |trace|
+          event.addEdgeStr(trace) if AppOpticsAPM::XTrace.task_id(trace) == task_id
+        end
+        log_event(layer, :exit, event)
+      end
+
+      ##
+      #:nodoc:
+      # Internal: Reports agent init to the collector
+      #
+      # ==== Attributes
+      #
+      # * +layer+ - The layer the reported event belongs to
+      # * +opts+ - A hash containing key/value pairs that will be reported along with this event
+      def log_init(layer = :rack, opts = {})
+        context = AppOpticsAPM::Metadata.makeRandom
+        if !context.isValid
+          return
+        end
+
+        event = context.createEvent
+        event.addInfo(APPOPTICS_STR_LAYER, layer.to_s)
+        event.addInfo(APPOPTICS_STR_LABEL, 'single')
+        opts.each do |k, v|
+          event.addInfo(k, v.to_s)
+        end
+
+        AppOpticsAPM::Reporter.sendStatus(event, context)
+      end
+
+      private
+
+      ##
+      #:nodoc:
+      # Internal: Report an event.
+      #
+      # ==== Attributes
+      #
+      # * +layer+ - The layer the reported event belongs to
+      # * +label+ - The label for the reported event.  See API documentation for reserved labels and usage.
+      # * +event+ - The pre-existing AppOpticsAPM context event.  See AppOpticsAPM::Context.createEvent
+      # * +opts+ - A hash containing key/value pairs that will be reported along with this event (optional).
+      #
+      # ==== Example
+      #
+      #   entry = AppOpticsAPM::Context.createEvent
+      #   AppOpticsAPM::API.log_event(:layer_name, 'entry',  entry_event, { :id => @user.id })
+      #
+      #   exit_event = AppOpticsAPM::Context.createEvent
+      #   exit_event.addEdge(entry.getMetadata)
+      #   AppOpticsAPM::API.log_event(:layer_name, 'exit',  exit_event, { :id => @user.id })
+      #
+      def log_event(layer, label, event, opts = {})
+        event.addInfo(APPOPTICS_STR_LAYER, layer.to_s.freeze) if layer
+        event.addInfo(APPOPTICS_STR_LABEL, label.to_s.freeze)
+
+        AppOpticsAPM.layer = layer.to_sym if label == :entry
+        AppOpticsAPM.layer = nil          if label == :exit
+
+        opts.each do |k, v|
+          value = nil
+
+          next unless valid_key? k
+
+          if @@ints_or_nil.include?(v.class)
+            value = v
+          elsif v.class == Set
+            value = v.to_a.to_s
+          else
+            value = v.to_s if v.respond_to?(:to_s)
+          end
+
+          begin
+            event.addInfo(k.to_s, value)
+          rescue ArgumentError => e
+            AppOpticsAPM.logger.debug "[AppOpticsAPM/debug] Couldn't add event KV: #{k} => #{v.class}"
+            AppOpticsAPM.logger.debug "[AppOpticsAPM/debug] #{e.message}"
+          end
+        end if !opts.nil? && opts.any?
+
+        AppOpticsAPM::Reporter.sendReport(event)
+      end
+
+    end
+  end
+end

data/lib/appoptics_apm/api/memcache.rb

@@ -0,0 +1,34 @@
+#--
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+#++
+
+module AppOpticsAPM
+  module API
+    ##
+    # Utility methods for the Memcache instrumentation
+    module Memcache
+      MEMCACHE_OPS = %w(add append cas decr decrement delete fetch get incr increment prepend replace set)
+
+      def memcache_hit?(result)
+        result.nil? ? 0 : 1
+      end
+
+      def remote_host(key)
+        return unless defined?(Lib.memcached_server_by_key) &&
+                      defined?(@struct) && defined?(is_unix_socket?)
+
+        server_as_array = Lib.memcached_server_by_key(@struct, key.to_s)
+
+        return unless server_as_array.is_a?(Array)
+
+        server = server_as_array.first
+        if is_unix_socket?(server)
+          'localhost'
+        elsif defined?(server.hostname)
+          server.hostname
+        end
+      end
+    end
+  end
+end

data/lib/appoptics_apm/api/profiling.rb

@@ -0,0 +1,201 @@
+#--
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+#++
+
+module AppOpticsAPM
+  module API
+    ##
+    # Module that provides profiling of arbitrary blocks of code
+    module Profiling
+      ##
+      # Public: Profile a given block of code. Detect any exceptions thrown by
+      # the block and report errors.
+      #
+      # profile_name - A name used to identify the block being profiled.
+      # report_kvs - A hash containing key/value pairs that will be reported along
+      #              with the event of this profile (optional).
+      # with_backtrace - Boolean to indicate whether a backtrace should
+      #                  be collected with this trace event.
+      #
+      # Example
+      #
+      #   def computation(n)
+      #     AppOpticsAPM::API.profile('fib', { :n => n }) do
+      #       fib(n)
+      #     end
+      #   end
+      #
+      # Returns the result of the block.
+      #
+
+      def profile(profile_name, report_kvs = {}, with_backtrace = false)
+        return yield unless AppOpticsAPM.tracing?
+
+        report_kvs[:Language] ||= :ruby
+        report_kvs[:ProfileName] ||= profile_name
+        report_kvs[:Backtrace] = AppOpticsAPM::API.backtrace if with_backtrace
+
+        AppOpticsAPM::API.log(nil, :profile_entry, report_kvs)
+
+        begin
+          yield
+        rescue => e
+          log_exception(nil, e)
+          raise
+        ensure
+          exit_kvs = {}
+          exit_kvs[:Language] = :ruby
+          exit_kvs[:ProfileName] = report_kvs[:ProfileName]
+
+          AppOpticsAPM::API.log(nil, :profile_exit, exit_kvs)
+        end
+      end
+
+      ##
+      # Public: Profile a method on a class or module.  That method can be of any (accessible)
+      # type (instance, singleton, private, protected etc.).
+      #
+      # klass  - the class or module that has the method to profile
+      # method - the method to profile.  Can be singleton, instance, private etc...
+      # opts   - a hash specifying the one or more of the following options:
+      #   * :arguments  - report the arguments passed to <tt>method</tt> on each profile (default: false)
+      #   * :result     - report the return value of <tt>method</tt> on each profile (default: false)
+      #   * :backtrace  - report the return value of <tt>method</tt> on each profile (default: false)
+      #   * :name       - alternate name for the profile reported in the dashboard (default: method name)
+      # extra_kvs - a hash containing any additional KVs you would like reported with the profile
+      #
+      # Example
+      #
+      #   opts = {}
+      #   opts[:backtrace] = true
+      #   opts[:arguments] = false
+      #   opts[:name] = :array_sort
+      #
+      #   AppOpticsAPM::API.profile_method(Array, :sort, opts)
+      #
+      def profile_method(klass, method, opts = {}, extra_kvs = {})
+        # If we're on an unsupported platform (ahem Mac), just act
+        # like we did something to nicely play the no-op part.
+        return true unless AppOpticsAPM.loaded
+
+        if RUBY_VERSION < '1.9.3'
+          AppOpticsAPM.logger.warn '[appoptics_apm/error] profile_method: Use the legacy method profiling for Ruby versions before 1.9.3'
+          return false
+
+        elsif !klass.is_a?(Module)
+          AppOpticsAPM.logger.warn "[appoptics_apm/error] profile_method: Not sure what to do with #{klass}.  Send a class or module."
+          return false
+
+        elsif !method.is_a?(Symbol)
+          if method.is_a?(String)
+            method = method.to_sym
+          else
+            AppOpticsAPM.logger.warn "[appoptics_apm/error] profile_method: Not sure what to do with #{method}.  Send a string or symbol for method."
+            return false
+          end
+        end
+
+        instance_method = klass.instance_methods.include?(method) || klass.private_instance_methods.include?(method)
+        class_method = klass.singleton_methods.include?(method)
+
+        # Make sure the request klass::method exists
+        if !instance_method && !class_method
+          AppOpticsAPM.logger.warn "[appoptics_apm/error] profile_method: Can't instrument #{klass}.#{method} as it doesn't seem to exist."
+          AppOpticsAPM.logger.warn "[appoptics_apm/error] #{__FILE__}:#{__LINE__}"
+          return false
+        end
+
+        # Strip '!' or '?' from method if present
+        safe_method_name = method.to_s.chop if method.to_s =~ /\?$|\!$/
+        safe_method_name ||= method
+
+        without_appoptics = "#{safe_method_name}_without_appoptics"
+        with_appoptics    = "#{safe_method_name}_with_appoptics"
+
+        # Check if already profiled
+        if klass.instance_methods.include?(with_appoptics.to_sym) ||
+           klass.singleton_methods.include?(with_appoptics.to_sym)
+          AppOpticsAPM.logger.warn "[appoptics_apm/error] profile_method: #{klass}::#{method} already profiled."
+          AppOpticsAPM.logger.warn "[appoptics_apm/error] profile_method: #{__FILE__}:#{__LINE__}"
+          return false
+        end
+
+        source_location = []
+        if instance_method
+          ::AppOpticsAPM::Util.send_include(klass, ::AppOpticsAPM::MethodProfiling)
+          source_location = klass.instance_method(method).source_location
+        elsif class_method
+          ::AppOpticsAPM::Util.send_extend(klass, ::AppOpticsAPM::MethodProfiling)
+          source_location = klass.method(method).source_location
+        end
+
+        report_kvs = collect_profile_kvs(klass, method, opts, extra_kvs, source_location)
+        report_kvs[:MethodName] = safe_method_name
+
+        if instance_method
+          klass.class_eval do
+            define_method(with_appoptics) do |*args, &block|
+              profile_wrapper(without_appoptics, report_kvs, opts, *args, &block)
+            end
+
+            alias_method without_appoptics, method.to_s
+            alias_method method.to_s, with_appoptics
+          end
+        elsif class_method
+          klass.define_singleton_method(with_appoptics) do |*args, &block|
+            profile_wrapper(without_appoptics, report_kvs, opts, *args, &block)
+          end
+
+          klass.singleton_class.class_eval do
+            alias_method without_appoptics, method.to_s
+            alias_method method.to_s, with_appoptics
+          end
+        end
+        true
+      end
+
+      private
+
+      ##
+      # Private: Helper method to aggregate KVs to report
+      #
+      # klass  - the class or module that has the method to profile
+      # method - the method to profile.  Can be singleton, instance, private etc...
+      # opts   - a hash specifying the one or more of the following options:
+      #   * :arguments  - report the arguments passed to <tt>method</tt> on each profile (default: false)
+      #   * :result     - report the return value of <tt>method</tt> on each profile (default: false)
+      #   * :backtrace  - report the return value of <tt>method</tt> on each profile (default: false)
+      #   * :name       - alternate name for the profile reported in the dashboard (default: method name)
+      # extra_kvs - a hash containing any additional KVs you would like reported with the profile
+      # source_location - array returned from klass.method(:name).source_location
+      #
+      def collect_profile_kvs(klass, method, opts, extra_kvs, source_location)
+        report_kvs = {}
+        report_kvs[:Language] ||= :ruby
+        report_kvs[:ProfileName] ||= opts[:name] ? opts[:name] : method
+
+        if klass.is_a?(Class)
+          report_kvs[:Class] = klass.to_s
+        else
+          report_kvs[:Module] = klass.to_s
+        end
+
+        # If this is a Rails Controller, report the KVs
+        if defined?(::AbstractController::Base) && klass.ancestors.include?(::AbstractController::Base)
+          report_kvs[:Controller] = klass.to_s
+          report_kvs[:Action] = method.to_s
+        end
+
+        # We won't have access to this info for native methods (those not defined in Ruby).
+        if source_location.is_a?(Array) && source_location.length == 2
+          report_kvs[:File] = source_location[0]
+          report_kvs[:LineNumber] = source_location[1]
+        end
+
+        # Merge in any extra_kvs requested
+        report_kvs.merge!(extra_kvs)
+      end
+    end
+  end
+end