appoptics_apm_mnfst 4.5.2

data/lib/appoptics_apm/api/memcache.rb

@@ -0,0 +1,37 @@
+#--
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+#++
+
+# TODO remove Memcache from API and into some Util module to be included in Modules that need
+# ____ these methods
+module AppOpticsAPM
+  module API
+    ##
+    # Utility methods for the Memcache instrumentation
+    # currently used by dalli and memcached
+    module Memcache #:nodoc:
+      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/metrics.rb

@@ -0,0 +1,55 @@
+module  AppOpticsAPM
+  module API
+    module Metrics
+
+      ##
+      # Internal: method to send duration for a transaction
+      # it checks if it can send metrics with the current transaction name
+      # or a default transaction name and sets the transaction name accordingly
+      #
+      # === Arguments:
+      #
+      # * +span+ the name of the current span (used to construct a transaction name if none is defined)
+      # * +kvs+ A hash containing key/value pairs, only the value of :TransactionName will be relevant
+      #
+      # === Returns:
+      # The result of the block.
+      #
+      # === Assigns:
+      # The transaction_name to kvs[:TransactionName]
+
+      def send_metrics(span, kvs)
+        start = Time.now
+        yield
+      ensure
+        duration = (1000 * 1000 * (Time.now - start)).to_i
+        transaction_name = determine_transaction_name(span, kvs)
+        kvs[:TransactionName] = AppOpticsAPM::Span.createSpan(transaction_name, nil, duration)
+        AppOpticsAPM.transaction_name = nil
+      end
+
+      private
+
+      ##
+      # Determine the transaction name to be set on the trace.
+      #
+      # === Argument:
+      # * +span+ the name of the current span (used to construct a transaction name if none is defined)
+      # * +kvs+ (hash, optional) the hash that may have values for 'Controller' and 'Action'
+      #
+      # === Returns:
+      # (string) the determined transaction name
+      #
+      def determine_transaction_name(span, kvs = {})
+        if AppOpticsAPM.transaction_name
+          AppOpticsAPM.transaction_name
+        elsif kvs['Controller'] && kvs['Action']
+          [kvs['Controller'], kvs['Action']].join('.')
+        else
+          "custom-#{span}"
+        end
+      end
+
+    end
+  end
+end

data/lib/appoptics_apm/api/profiling.rb

@@ -0,0 +1,203 @@
+#--
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+#++
+
+module AppOpticsAPM
+  module API
+    ##
+    # Module to create profiling traces for blocks of code or methods
+    module Profiling
+      ##
+      # Public: Profile a given block of code. Detect any exceptions thrown by
+      # the block and report errors.
+      #
+      # ==== Arguments
+      #
+      # * +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?
+
+        begin
+          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
+      end
+
+      ##
+      # Public: Add profiling to a method on a class or module.  That method can be of any (accessible)
+      # type (instance, singleton, private, protected etc.).
+      #
+      # ==== Arguments
+      #
+      # * +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 key/value pairs 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 !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
+        end
+
+        if method.is_a?(String)
+          method = method.to_sym
+        elsif !method.is_a?(Symbol)
+          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
+
+        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
+
+        klass.is_a?(Class) ? report_kvs[:Class] = klass.to_s : report_kvs[:Module] = klass.to_s
+
+        # 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
+
+
+      # need to set the context to public, otherwise the following `extends` will be private in api.rb
+      public
+
+    end
+  end
+end

data/lib/appoptics_apm/api/tracing.rb

@@ -0,0 +1,53 @@
+#--
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+#++
+
+module AppOpticsAPM
+  module API
+    ##
+    # Provides the higher-level tracing interface for the API
+    #
+    # The tracing methods have been moved to AppOpticsAPM::SDK and AppOpticsAPM::API extends all methods from the SDK
+    # except for start_trace.
+    # AppOpticsAPM::API.start_trace is kept for backwards compatibility because it returns an array
+    # whereas AppOpticsAPM::SDK.start_trace will only return the result of the block.
+    #
+
+    module Tracing
+
+      # Public: Collect metrics and start tracing a given block of code. A
+      # trace will be started depending on configuration and probability.
+      # Detect any exceptions thrown by the block and report errors.
+      #
+      # When start_trace returns control to the calling context, the trace will be
+      # completed and the tracing context will be cleared.
+      #
+      # ==== Arguments
+      #
+      # * +span+   - name for the span to be used as label in the trace view
+      # * +xtrace+ - (optional) incoming X-Trace identifier to be continued
+      # * +opts+   - (optional) hash containing key/value pairs that will be reported along
+      #              with the first event of this span
+      #
+      # ==== Example
+      #
+      #   def handle_request(request, response)
+      #     # ... code that modifies request and response ...
+      #   end
+      #
+      #   def handle_request_with_appoptics(request, response)
+      #     start_trace('custom_span', nil, :TransactionName => 'handle_request') do
+      #       handle_request(request, response)
+      #     end
+      #   end
+      #
+      # Returns an array with the result of the block and the last xtrace used
+      def start_trace(span, xtrace = nil, opts = {})
+        target = {}
+        [start_trace_with_target(span, xtrace, target, opts) { yield }, target['X-Trace']]
+      end
+
+    end
+  end
+end

data/lib/appoptics_apm/api/util.rb

@@ -0,0 +1,122 @@
+#--
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+#++
+
+require 'pp'
+
+module AppOpticsAPM
+  module API
+    ##
+    # General utility methods for the gem
+    module Util #:nodoc:
+      BACKTRACE_CUTOFF = 200
+
+      # Internal: Check whether the provided key is reserved or not. Reserved
+      # keys are either keys that are handled by liboboe calls or the appoptics_apm gem.
+      #
+      # key - the key to check.
+      #
+      # Return a boolean indicating whether or not key is reserved.
+      def valid_key?(key)
+        ![:Label, :Layer, :Edge, :Timestamp, :Timestamp_u].include?(key.to_sym)
+      end
+
+      # Internal: Get the current backtrace.
+      #
+      # ignore - Number of frames to ignore at the top of the backtrace. Use
+      #          when you know how many layers deep in the key call is being
+      #          made.
+      #
+      # Returns a string with each frame of the backtrace separated by '\r\n'.
+      #
+      def backtrace(ignore = 0)
+        bt = Kernel.caller
+        bt.slice!(0, ignore)
+        trim_backtrace(bt).join("\r\n")
+      end
+
+      # Internal: Trim a backtrace to a manageable size
+      #
+      # backtrace - the backtrace (an array of stack frames/from Kernel.caller)
+      #
+      # Returns a trimmed backtrace
+      def trim_backtrace(backtrace)
+        return backtrace unless backtrace.is_a?(Array) && backtrace.size > BACKTRACE_CUTOFF
+
+        # Trim backtraces by getting the first 180 and last 20 lines
+        backtrace[0, 180] + ['...[snip]...'] + backtrace[backtrace.size - 20, 20]
+      end
+
+      # Internal: Check if a host is blacklisted from tracing
+      #
+      # addr_port - the addr_port from Net::HTTP although this method
+      # can be used from any component in reality
+      #
+      # Returns a boolean on blacklisted state
+      def blacklisted?(addr_port)
+        return false unless AppOpticsAPM::Config.blacklist
+
+        # Ensure that the blacklist is an array
+        unless AppOpticsAPM::Config.blacklist.is_a?(Array)
+          val = AppOpticsAPM::Config[:blacklist]
+          AppOpticsAPM::Config[:blacklist] = [val.to_s]
+        end
+
+        AppOpticsAPM::Config.blacklist.each do |h|
+          return true if addr_port.to_s.match(h.to_s)
+        end
+
+        false
+      end
+
+      # Internal: Pretty print a list of arguments for reporting
+      #
+      # args - the list of arguments to work on
+      #
+      # Returns a pretty string representation of arguments
+      def pps(*args)
+        old_out = $stdout
+        begin
+          s = StringIO.new
+          $stdout = s
+          pp(*args)
+        ensure
+          $stdout = old_out
+        end
+        s.string
+      end
+
+      # Internal: Determine a string to report representing klass
+      #
+      # args - an instance of a Class, a Class or a Module
+      #
+      # Returns a string representation of klass
+      def get_class_name(klass)
+        kv = {}
+
+        if klass.to_s =~ /::/
+          klass.class.to_s.rpartition('::').last
+        else
+          if klass.is_a?(Class) && klass.is_a?(Module)
+            # Class
+            kv['Class'] = klass.to_s
+
+          elsif !klass.is_a?(Class) && !klass.is_a?(Module)
+            # Class instance
+            kv['Class'] = klass.class.to_s
+
+          else
+            # Module
+            kv['Module'] = klass.to_s
+          end
+        end
+        kv
+      end
+
+      def xtrace_v2?(xtr)
+        return xtr && xtr.start_with?('2B')
+      end
+    end
+  end
+end