appoptics_apm 4.0.2

data/lib/appoptics_apm/api/tracing.rb

@@ -0,0 +1,152 @@
+#--
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+#++
+
+module AppOpticsAPM
+  module API
+    ##
+    # Provides the higher-level tracing interface for the API.
+    #
+    # Traces are best created with a <tt>AppOpticsAPM:API.start_trace</tt> block and
+    # <tt>AppOpticsAPM:API.trace</tt> blocks around calls to be traced.
+    # These two methods guarantee proper nesting of tracing and handling of the tracing context.
+    #
+    # Some optional keys that can be used in the +opts+ hash:
+    # * +:TransactionName+ - this will show up in the transactions column in the traces dashboard
+    # * +:Controller+ - if present will be combined with +Action+ and show up as transaction in the traces dashboard
+    # * +:Action+ - if present will be combined with +Controller+ and show up as transaction in the traces dashboard
+    # * +:HTTP-Host+ - domain portion of URL
+    # * +:URL+ - request URI
+    # * +:Method+
+    #
+    # Invalid keys: +:Label+, +:Layer+, +:Edge+, +:Timestamp+, +:Timestamp_u+
+    #
+    module Tracing
+      # Public: Trace a given block of code. Detect any exceptions thrown by
+      # the block and report errors.
+      #
+      # * +:layer+ - The layer the block of code belongs to.
+      # * +:opts+ - A hash containing key/value pairs that will be reported along
+      #   with the first event of this layer (optional).
+      # * +:protect_op+ - The operation being traced.  Used to avoid
+      #   double tracing operations that call each other
+      #
+      # Example
+      #
+      #   def computation(n)
+      #     fib(n)
+      #     raise Exception.new
+      #   end
+      #
+      #   def computation_with_oboe(n)
+      #     trace('fib', { :number => n }, :fib) do
+      #       computation(n)
+      #     end
+      #   end
+      #
+      #   result = computation_with_oboe(1000)
+      #
+      # Returns the result of the block.
+      def trace(layer, opts = {}, protect_op = nil)
+        log_entry(layer, opts, protect_op)
+        begin
+          yield
+        rescue Exception => e
+          log_exception(layer, e)
+          raise
+        ensure
+          log_exit(layer)
+        end
+      end
+
+      # Public: Trace a given block of code which can start a trace 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 oboe
+      # context will be cleared.
+      #
+      # layer - The layer the block of code belongs to.
+      # opts - A hash containing key/value pairs that will be reported along
+      # with the first event of this layer (optional).
+      #
+      # Example
+      #
+      #   def handle_request(request, response)
+      #     # ... code that modifies request and response ...
+      #   end
+      #
+      #   def handle_request_with_oboe(request, response)
+      #     result, xtrace = start_trace('rails', request['X-Trace']) do
+      #       handle_request(request, response)
+      #     end
+      #     result
+      #   rescue Exception => e
+      #     xtrace = e.xtrace
+      #   ensure
+      #     response['X-trace'] = xtrace
+      #   end
+      #
+      # Returns a list of length two, the first element of which is the result
+      # of the block, and the second element of which is the oboe context that
+      # was set when the block completed execution.
+      def start_trace(layer, xtrace = nil, opts = {})
+        log_start(layer, xtrace, opts)
+        begin
+          result = yield
+        rescue Exception => e
+          log_exception(layer, e)
+          e.instance_variable_set(:@xtrace, log_end(layer))
+          raise
+        end
+        xtrace = log_end(layer)
+
+        [result, xtrace]
+      end
+
+      # Public: Trace a given block of code which can start a trace depending
+      # on configuration and probability. Detect any exceptions thrown by the
+      # block and report errors. Assign an X-Trace to the target.
+      #
+      # The motivating use case for this is HTTP streaming in rails3. We need
+      # access to the exit event's trace id so we can set the header before any
+      # work is done, and before any headers are sent back to the client.
+      #
+      # layer - The layer the block of code belongs to.
+      # xtrace - string - The X-Trace to continue by the target
+      # target - has to respond to #[]=, The target object in which to place the trace information
+      # opts - A hash containing key/value pairs that will be reported along
+      #        with the first event of this layer (optional).
+      #
+      # Example:
+      #
+      #   def handle_request(request, response)
+      #     # ... code that does something with request and response ...
+      #   end
+      #
+      #   def handle_request_with_oboe(request, response)
+      #     start_trace_with_target('rails', request['X-Trace'], response) do
+      #       handle_request(request, response)
+      #     end
+      #   end
+      #
+      # Returns the result of the block.
+      def start_trace_with_target(layer, xtrace, target, opts = {})
+        log_start(layer, xtrace, opts)
+        exit_evt = AppOpticsAPM::Context.createEvent
+        begin
+          target['X-Trace'] = AppOpticsAPM::EventUtil.metadataString(exit_evt) if AppOpticsAPM.tracing?
+          yield
+        rescue Exception => e
+          log_exception(layer, e)
+          raise
+        ensure
+          exit_evt.addEdge(AppOpticsAPM::Context.get)
+          log(layer, :exit, {}, exit_evt)
+          AppOpticsAPM::Context.clear
+        end
+      end
+    end
+  end
+end

data/lib/appoptics_apm/api/util.rb

@@ -0,0 +1,128 @@
+#--
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+#++
+
+require 'pp'
+
+module AppOpticsAPM
+  module API
+    ##
+    # General utility methods for the gem
+    module Util
+      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)
+
+        length = backtrace.size
+        if length > BACKTRACE_CUTOFF
+          # Trim backtraces by getting the first 180 and last 20 lines
+          trimmed = backtrace[0, 180] + ['...[snip]...'] + backtrace[length - 20, 20]
+        else
+          trimmed = backtrace
+        end
+        trimmed
+      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

data/lib/appoptics_apm/api.rb

@@ -0,0 +1,18 @@
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+
+module AppOpticsAPM
+  ##
+  # This module implements the AppOpticsAPM tracing API.
+  # See: https://github.com/librato/ruby-appoptics#the-tracing-api
+  # and/or: http://rdoc.info/gems/appoptics_apm/AppOpticsAPM/API/Tracing
+  module API
+    def self.extend_with_tracing
+      extend AppOpticsAPM::API::Logging
+      extend AppOpticsAPM::API::Tracing
+      extend AppOpticsAPM::API::Profiling
+      extend AppOpticsAPM::API::LayerInit
+    end
+    extend AppOpticsAPM::API::Util
+  end
+end

data/lib/appoptics_apm/base.rb

@@ -0,0 +1,252 @@
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+
+# Constants from liboboe
+OBOE_TRACE_NEVER   = 0
+OBOE_TRACE_ALWAYS  = 1
+OBOE_TRACE_THROUGH = 2
+
+OBOE_SAMPLE_RATE_SOURCE_FILE                   = 1
+OBOE_SAMPLE_RATE_SOURCE_DEFAULT                = 2
+OBOE_SAMPLE_RATE_SOURCE_OBOE                   = 3
+OBOE_SAMPLE_RATE_SOURCE_LAST_OBOE              = 4
+OBOE_SAMPLE_RATE_SOURCE_DEFAULT_MISCONFIGURED  = 5
+OBOE_SAMPLE_RATE_SOURCE_OBOE_DEFAULT           = 6
+
+# Masks for bitwise ops
+ZERO_MASK = 0b0000000000000000000000000000
+
+SAMPLE_RATE_MASK   = 0b0000111111111111111111111111
+SAMPLE_SOURCE_MASK = 0b1111000000000000000000000000
+
+ZERO_SAMPLE_RATE_MASK   = 0b1111000000000000000000000000
+ZERO_SAMPLE_SOURCE_MASK = 0b0000111111111111111111111111
+
+APPOPTICS_STR_BLANK = ''.freeze
+APPOPTICS_STR_LAYER = 'Layer'.freeze
+APPOPTICS_STR_LABEL = 'Label'.freeze
+
+# Used in tests to store local trace data
+TRACE_FILE = '/tmp/appoptics_traces.bson'.freeze
+
+##
+# This module is the base module for the various implementations of AppOpticsAPM reporting.
+# Current variations as of 2014-09-10 are a c-extension, JRuby (using AppOpticsAPM Java
+# instrumentation) and a Heroku c-extension (with embedded tracelyzer)
+module AppOpticsAPMBase
+  extend ::AppOpticsAPM::ThreadLocal
+
+  attr_accessor :reporter
+  attr_accessor :loaded
+  thread_local :sample_source
+  thread_local :sample_rate
+  thread_local :layer
+  thread_local :layer_op
+  # Semaphore used during the test suite to test
+  # global config options.
+  thread_local :config_lock
+
+  # The following accessors indicate the incoming tracing state received
+  # by the rack layer.  These are primarily used to identify state
+  # between the Ruby and JAppOpticsAPM instrumentation under JRuby.
+  #
+  # This is because that even though there may be an incoming
+  # X-Trace request header, tracing may have already been started
+  # by Joboe.  Such a scenario occurs when the application is being
+  # hosted by a Java container (such as Tomcat or Glassfish) and
+  # JAppOpticsAPM has already initiated tracing.  In this case, we shouldn't
+  # pickup the X-Trace context in the X-Trace header and we shouldn't
+  # set the outgoing response X-Trace header or clear context.
+  # Yeah I know.  Yuck.
+
+  # Occurs only on Jruby.  Indicates that Joboe (the java instrumentation)
+  # has already started tracing before it hit the JRuby instrumentation.
+  thread_local :has_incoming_context
+
+  # Indicates the existence of a valid X-Trace request header
+  thread_local :has_xtrace_header
+
+  # This indicates that this trace was continued from
+  # an incoming X-Trace request header or in the case
+  # of JRuby, a trace already started by JAppOpticsAPM.
+  thread_local :is_continued_trace
+
+  ##
+  # extended
+  #
+  # Invoked when this module is extended.
+  # e.g. extend AppOpticsAPMBase
+  #
+  def self.extended(cls)
+    cls.loaded = true
+
+    # This gives us pretty accessors with questions marks at the end
+    # e.g. is_continued_trace --> is_continued_trace?
+    AppOpticsAPM.methods.select { |m| m =~ /^is_|^has_/ }.each do |c|
+      unless c =~ /\?$|=$/
+        # AppOpticsAPM.logger.debug "aliasing #{c}? to #{c}"
+        alias_method "#{c}?", c
+      end
+    end
+  end
+
+  ##
+  # pickup_context
+  #
+  # Determines whether we should pickup context
+  # from an incoming X-Trace request header.  The answer
+  # is generally yes but there are cases in JRuby under
+  # Tomcat (or Glassfish etc.) where tracing may have
+  # been already started by the Java instrumentation (Joboe)
+  # in which case we don't want to do this.
+  #
+  def pickup_context?(xtrace)
+    return false unless AppOpticsAPM::XTrace.valid?(xtrace)
+
+    if defined?(JRUBY_VERSION) && AppOpticsAPM.tracing?
+      return false
+    else
+      return true
+    end
+  end
+
+  ##
+  # tracing_layer?
+  #
+  # Queries the thread local variable about the current
+  # layer being traced.  This is used in cases of recursive
+  # operation tracing or one instrumented operation calling another.
+  #
+  def tracing_layer?(layer)
+    AppOpticsAPM.layer == layer.to_sym
+  end
+
+  ##
+  # tracing_layer_op?
+  #
+  # Queries the thread local variable about the current
+  # operation being traced.  This is used in cases of recursive
+  # operation tracing or one instrumented operation calling another.
+  #
+  # <operation> can be a single symbol or an array of symbols that
+  # will be checked against.
+  #
+  # In such cases, we only want to trace the outermost operation.
+  #
+  def tracing_layer_op?(operation)
+    if operation.is_a?(Array)
+      operation.include?(AppOpticsAPM.layer_op)
+    else
+      AppOpticsAPM.layer_op == operation.to_sym
+    end
+  end
+
+  ##
+  # Returns true if the tracing_mode is set to always.
+  # False otherwise
+  #
+  def always?
+    AppOpticsAPM::Config[:tracing_mode] &&
+      AppOpticsAPM::Config[:tracing_mode].to_sym == :always
+  end
+
+  ##
+  # Returns true if the tracing_mode is set to never.
+  # False otherwise
+  #
+  def never?
+    AppOpticsAPM::Config[:tracing_mode] &&
+      AppOpticsAPM::Config[:tracing_mode].to_sym == :never
+  end
+
+  ##
+  # Returns true if we are currently tracing a request
+  # False otherwise
+  #
+  def tracing?
+    return false if !AppOpticsAPM.loaded || AppOpticsAPM.never?
+    AppOpticsAPM::Context.isSampled
+  end
+
+  def heroku?
+    ENV.key?('APPOPTICS_URL')
+  end
+
+  ##
+  # Determines if we are running under a forking webserver
+  #
+  def forking_webserver?
+    if (defined?(::Unicorn) && ($PROGRAM_NAME =~ /unicorn/i)) ||
+       (defined?(::Puma) && ($PROGRAM_NAME =~ /puma/i))
+      true
+    else
+      false
+    end
+  end
+
+  ##
+  # Debugging helper method
+  #
+  def pry!
+    # Only valid for development or test environments
+    env = ENV['RACK_ENV'] || ENV['RAILS_ENV']
+    return unless %w(development, test).include? env
+
+    if RUBY_VERSION > '1.9.3'
+      require 'pry'
+      require 'pry-byebug'
+
+      if defined?(PryByebug)
+        Pry.commands.alias_command 'c', 'continue'
+        Pry.commands.alias_command 's', 'step'
+        Pry.commands.alias_command 'n', 'next'
+        Pry.commands.alias_command 'f', 'finish'
+
+        Pry::Commands.command(/^$/, 'repeat last command') do
+          _pry_.run_command Pry.history.to_a.last
+        end
+      end
+
+      byebug
+    else
+      require 'ruby-debug'; debugger
+    end
+  end
+
+  ##
+  # Indicates whether a supported framework is in use
+  # or not
+  #
+  def framework?
+    defined?(::Rails) || defined?(::Sinatra) || defined?(::Padrino) || defined?(::Grape)
+  end
+
+  ##
+  # These methods should be implemented by the descendants
+  # (Oboe_metal, JOboe_metal (JRuby), Heroku_metal)
+  #
+  def sample?(_opts = {})
+    fail 'sample? should be implemented by metal layer.'
+  end
+
+  def log(_layer, _label, _options = {})
+    fail 'log should be implemented by metal layer.'
+  end
+
+  def set_tracing_mode(_mode)
+    fail 'set_tracing_mode should be implemented by metal layer.'
+  end
+
+  def set_sample_rate(_rate)
+    fail 'set_sample_rate should be implemented by metal layer.'
+  end
+end
+
+module AppOpticsAPM
+  extend AppOpticsAPMBase
+end
+
+# Setup an alias so we don't bug users
+# about single letter capitalization
+Appoptics = AppOpticsAPM
+AO = AppOpticsAPM