traceview 3.0.0-java

data/lib/traceview/api/util.rb

@@ -0,0 +1,121 @@
+# Copyright (c) 2013 AppNeta, Inc.
+# All rights reserved.
+
+require 'pp'
+
+module TraceView
+  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 traceview gem.
+      #
+      # key - the key to check.
+      #
+      # Return a boolean indicating whether or not key is reserved.
+      def valid_key?(key)
+        !%w(Label Layer Edge Timestamp Timestamp_u).include? key.to_s
+      end
+
+      # Internal: Get the current backtrace.
+      #
+      # ignore - Number of frames to ignore at the end of the backtrace. Use
+      #          when you know how many layers deep in oboe the call is being
+      #          made.
+      #
+      # Returns a string with each frame of the backtrace separated by '\r\n'.
+      #
+      # FIXME: ignore is not currently used (see BACKTRACE_CUTOFF)
+      def backtrace(_ignore = 1)
+        trim_backtrace(Kernel.caller).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 TraceView::Config.blacklist
+
+        # Ensure that the blacklist is an array
+        unless TraceView::Config.blacklist.is_a?(Array)
+          val = TraceView::Config[:blacklist]
+          TraceView::Config[:blacklist] = [val.to_s]
+        end
+
+        TraceView::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
+    end
+  end
+end

data/lib/traceview/api.rb

@@ -0,0 +1,18 @@
+# Copyright (c) 2013 AppNeta, Inc.
+# All rights reserved.
+
+module TraceView
+  ##
+  # This module implements the TraceView tracing API.
+  # See: https://github.com/appneta/oboe-ruby#the-tracing-api
+  # and/or: http://rdoc.info/gems/oboe/Oboe/API/Tracing
+  module API
+    def self.extend_with_tracing
+      extend TraceView::API::Logging
+      extend TraceView::API::Tracing
+      extend TraceView::API::Profiling
+      extend TraceView::API::LayerInit
+    end
+    extend TraceView::API::Util
+  end
+end

data/lib/traceview/base.rb

@@ -0,0 +1,225 @@
+# Copyright (c) 2013 AppNeta, Inc.
+# 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
+
+##
+# This module is the base module for the various implementations of TraceView reporting.
+# Current variations as of 2014-09-10 are a c-extension, JRuby (using TraceView Java
+# instrumentation) and a Heroku c-extension (with embedded tracelyzer)
+module TraceViewBase
+  extend ::TraceView::ThreadLocal
+
+  attr_accessor :reporter
+  attr_accessor :loaded
+  thread_local :sample_source
+  thread_local :sample_rate
+  thread_local :layer
+  thread_local :layer_op
+
+  # The following accessors indicate the incoming tracing state received
+  # by the rack layer.  These are primarily used to identify state
+  # between the Ruby and JTraceView 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
+  # JTraceView 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 JTraceView.
+  thread_local :is_continued_trace
+
+  ##
+  # extended
+  #
+  # Invoked when this module is extended.
+  # e.g. extend TraceViewBase
+  #
+  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?
+    TraceView.methods.select{ |m| m =~ /^is_|^has_/ }.each do |c|
+      unless c =~ /\?$|=$/
+        # TraceView.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 TraceView::XTrace.valid?(xtrace)
+
+    if defined?(JRUBY_VERSION) && TraceView.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)
+    return TraceView.layer == layer
+  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.
+  #
+  # In such cases, we only want to trace the outermost operation.
+  #
+  def tracing_layer_op?(operation)
+    if operation.is_a?(Array)
+      return operation.include?(TraceView.layer_op)
+    else
+      return TraceView.layer_op == operation
+    end
+  end
+
+  ##
+  # Returns true if the tracing_mode is set to always.
+  # False otherwise
+  #
+  def always?
+    TraceView::Config[:tracing_mode].to_s == 'always'
+  end
+
+  ##
+  # Returns true if the tracing_mode is set to never.
+  # False otherwise
+  #
+  def never?
+    TraceView::Config[:tracing_mode].to_s == 'never'
+  end
+
+  ##
+  # Returns true if the tracing_mode is set to always or through.
+  # False otherwise
+  #
+  def passthrough?
+    %w(always through).include?(TraceView::Config[:tracing_mode])
+  end
+
+  ##
+  # Returns true if the tracing_mode is set to through.
+  # False otherwise
+  #
+  def through?
+    TraceView::Config[:tracing_mode] == 'through'
+  end
+
+  ##
+  # Returns true if we are currently tracing a request
+  # False otherwise
+  #
+  def tracing?
+    return false unless TraceView.loaded
+
+    TraceView::Context.isValid && !TraceView.never?
+  end
+
+  def log(layer, label, options = {})
+    # WARN: TraceView.log will be deprecated in a future release.  Please use TraceView::API.log instead.
+    TraceView::API.log(layer, label, options)
+  end
+
+  def heroku?
+    ENV.key?('TRACEVIEW_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
+
+  ##
+  # Indicates whether a supported framework is in use
+  # or not
+  #
+  def framework?
+    defined?(::Rails) or defined?(::Sinatra) or defined?(::Padrino) or 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 TraceView
+  extend TraceViewBase
+end

data/lib/traceview/config.rb

@@ -0,0 +1,238 @@
+# Copyright (c) 2013 AppNeta, Inc.
+# All rights reserved.
+
+module TraceView
+  ##
+  # This module exposes a nested configuration hash that can be used to
+  # configure and/or modify the functionality of the traceview gem.
+  #
+  # Use TraceView::Config.show to view the entire nested hash.
+  #
+  module Config
+    @@config = {}
+
+    @@instrumentation = [:action_controller, :action_view, :active_record,
+                         :cassandra, :dalli, :em_http_request, :excon, :faraday,
+                         :grape, :httpclient, :nethttp, :memcached, :memcache, :mongo,
+                         :moped, :rack, :redis, :resque, :rest_client, :sequel,
+                         :typhoeus]
+
+    # Subgrouping of instrumentation
+    @@http_clients = [:excon, :faraday, :httpclient, :nethttp, :rest_client, :typhoeus]
+
+    ##
+    # Return the raw nested hash.
+    #
+    def self.show
+      @@config
+    end
+
+    def self.initialize(_data = {})
+      # Setup default instrumentation values
+      @@instrumentation.each do |k|
+        @@config[k] = {}
+        @@config[k][:enabled] = true
+        @@config[k][:collect_backtraces] = false
+        @@config[k][:log_args] = true
+      end
+
+      # Beta instrumentation disabled by default
+      TraceView::Config[:em_http_request][:enabled] = false
+
+      # Set collect_backtraces defaults
+      TraceView::Config[:action_controller][:collect_backtraces] = true
+      TraceView::Config[:active_record][:collect_backtraces] = true
+      TraceView::Config[:action_view][:collect_backtraces] = true
+      TraceView::Config[:cassandra][:collect_backtraces] = true
+      TraceView::Config[:dalli][:collect_backtraces] = false
+      TraceView::Config[:em_http_request][:collect_backtraces] = false
+      TraceView::Config[:excon][:collect_backtraces] = true
+      TraceView::Config[:faraday][:collect_backtraces] = false
+      TraceView::Config[:grape][:collect_backtraces] = true
+      TraceView::Config[:httpclient][:collect_backtraces] = true
+      TraceView::Config[:memcache][:collect_backtraces] = false
+      TraceView::Config[:memcached][:collect_backtraces] = false
+      TraceView::Config[:mongo][:collect_backtraces] = true
+      TraceView::Config[:moped][:collect_backtraces] = true
+      TraceView::Config[:nethttp][:collect_backtraces] = true
+      TraceView::Config[:redis][:collect_backtraces] = false
+      TraceView::Config[:resque][:collect_backtraces] = true
+      TraceView::Config[:rest_client][:collect_backtraces] = false
+      TraceView::Config[:sequel][:collect_backtraces] = true
+      TraceView::Config[:typhoeus][:collect_backtraces] = false
+
+      # Special instrument specific flags
+      #
+      # :link_workers - associates enqueue operations with the jobs they queue by piggybacking
+      #                 an additional argument that is stripped prior to job proecessing
+      #                 !!Note: Make sure both the queue side and the Resque workers are instrumented
+      #                 or jobs will fail
+      #                 (Default: false)
+      @@config[:resque][:link_workers] = false
+
+      # Setup an empty host blacklist (see: TraceView::API::Util.blacklisted?)
+      @@config[:blacklist] = []
+
+      # Access Key is empty until loaded from config file or env var
+      @@config[:access_key] = ''
+
+      # Logging of outgoing HTTP query args
+      #
+      # This optionally disables the logging of query args of outgoing
+      # HTTP clients such as Net::HTTP, excon, typhoeus and others.
+      #
+      # This flag is global to all HTTP client instrumentation.
+      #
+      # To configure this on a per instrumentation basis, set this
+      # option to true and instead disable the instrumenstation specific
+      # option <tt>log_args</tt>:
+      #
+      #   TraceView::Config[:nethttp][:log_args] = false
+      #   TraceView::Config[:excon][:log_args] = false
+      #   TraceView::Config[:typhoeus][:log_args] = true
+      #
+      @@config[:include_url_query_params] = true
+
+      # Logging of incoming HTTP query args
+      #
+      # This optionally disables the logging of incoming URL request
+      # query args.
+      #
+      # This flag is global and currently only affects the Rack
+      # instrumentation which reports incoming request URLs and
+      # query args by default.
+      @@config[:include_remote_url_params] = true
+
+      # The TraceView Ruby gem has the ability to sanitize query literals
+      # from SQL statements.  By default this is disabled.  Enable to
+      # avoid collecting and reporting query literals to TraceView.
+      @@config[:sanitize_sql] = false
+
+      # Do Not Trace
+      # These two values allow you to configure specific URL patterns to
+      # never be traced.  By default, this is set to common static file
+      # extensions but you may want to customize this list for your needs.
+      #
+      # dnt_regexp and dnt_opts is passed to Regexp.new to create
+      # a regular expression object.  That is then used to match against
+      # the incoming request path.
+      #
+      # The path string originates from the rack layer and is retrieved
+      # as follows:
+      #
+      #   req = ::Rack::Request.new(env)
+      #   path = URI.unescape(req.path)
+      #
+      # Usage:
+      #   TraceView::Config[:dnt_regexp] = "lobster$"
+      #   TraceView::Config[:dnt_opts]   = Regexp::IGNORECASE
+      #
+      # This will ignore all requests that end with the string lobster
+      # regardless of case
+      #
+      # Requests with positive matches (non nil) will not be traced.
+      # See lib/traceview/util.rb: TraceView::Util.static_asset?
+      #
+      @@config[:dnt_regexp] = "\.(jpg|jpeg|gif|png|ico|css|zip|tgz|gz|rar|bz2|pdf|txt|tar|wav|bmp|rtf|js|flv|swf|ttf|woff|svg|less)$"
+      @@config[:dnt_opts]   = Regexp::IGNORECASE
+
+      # In Rails, raised exceptions with rescue handlers via
+      # <tt>rescue_from</tt> are not reported to the TraceView
+      # dashboard by default.  Setting this value to true will
+      # report all raised exception regardless.
+      @@config[:report_rescued_errors] = false
+
+      # Environment support for OpenShift.
+      if ENV.key?('OPENSHIFT_TRACEVIEW_TLYZER_IP')
+        # We're running on OpenShift
+        @@config[:tracing_mode] = 'always'
+        @@config[:reporter_host] = ENV['OPENSHIFT_TRACEVIEW_TLYZER_IP']
+        @@config[:reporter_port] = ENV['OPENSHIFT_TRACEVIEW_TLYZER_PORT']
+      else
+        # The default configuration
+        @@config[:tracing_mode] = 'through'
+        @@config[:reporter_host] = '127.0.0.1'
+        @@config[:reporter_port] = '7831'
+      end
+
+      @@config[:verbose] = ENV.key?('TRACEVIEW_GEM_VERBOSE') ? true : false
+    end
+
+    def self.update!(data)
+      data.each do |key, value|
+        self[key] = value
+      end
+    end
+
+    def self.merge!(data)
+      self.update!(data)
+    end
+
+    def self.[](key)
+      @@config[key.to_sym]
+    end
+
+    def self.[]=(key, value)
+      @@config[key.to_sym] = value
+
+      if key == :sampling_rate
+        TraceView.logger.warn 'sampling_rate is not a supported setting for TraceView::Config.  ' \
+                         'Please use :sample_rate.'
+
+      elsif key == :sample_rate
+        unless value.is_a?(Integer) || value.is_a?(Float)
+          fail 'traceview :sample_rate must be a number between 1 and 1000000 (1m)'
+        end
+
+        # Validate :sample_rate value
+        unless value.between?(1, 1e6)
+          fail 'traceview :sample_rate must be between 1 and 1000000 (1m)'
+        end
+
+        # Assure value is an integer
+        @@config[key.to_sym] = value.to_i
+        TraceView.set_sample_rate(value) if TraceView.loaded
+
+      elsif key == :include_url_query_params
+        # Obey the global flag and update all of the per instrumentation
+        # <tt>:log_args</tt> values.
+        @@http_clients.each do |i|
+          @@config[i][:log_args] = value
+        end
+
+      elsif key == :include_remote_url_params
+        # Obey the global flag and update all of the per instrumentation
+        # <tt>:log_args</tt> values.
+        @@config[:rack][:log_args] = value
+      end
+
+      # Update liboboe if updating :tracing_mode
+      if key == :tracing_mode
+        TraceView.set_tracing_mode(value) if TraceView.loaded
+      end
+    end
+
+    def self.method_missing(sym, *args)
+      class_var_name = "@@#{sym}"
+
+      if sym.to_s =~ /(.+)=$/
+        self[$1] = args.first
+      else
+        # Try part of the @@config hash first
+        if @@config.key?(sym)
+          self[sym]
+
+        # Then try as a class variable
+        elsif self.class_variable_defined?(class_var_name.to_sym)
+          self.class_eval(class_var_name)
+
+        # Congrats - You've won a brand new nil...
+        else
+          nil
+        end
+      end
+    end
+  end
+end
+
+TraceView::Config.initialize

data/lib/traceview/frameworks/grape.rb

@@ -0,0 +1,97 @@
+# Copyright (c) 2013 AppNeta, Inc.
+# All rights reserved.
+
+module TraceView
+  module Grape
+    module API
+      def self.extended(klass)
+        ::TraceView::Util.class_method_alias(klass, :inherited, ::Grape::API)
+      end
+
+      def inherited_with_traceview(subclass)
+        inherited_without_traceview(subclass)
+
+        subclass.use ::TraceView::Rack
+      end
+    end
+
+    module Endpoint
+      def self.included(klass)
+        ::TraceView::Util.method_alias(klass, :run, ::Grape::Endpoint)
+      end
+
+      def run_with_traceview(env)
+        if TraceView.tracing?
+          report_kvs = {}
+
+          report_kvs[:Controller] = self.class
+          report_kvs[:Action] = env['PATH_INFO']
+
+          # Fall back to the raw tracing API so we can pass KVs
+          # back on exit (a limitation of the TraceView::API.trace
+          # block method) This removes the need for an info
+          # event to send additonal KVs
+          ::TraceView::API.log_entry('grape', {})
+
+          begin
+            run_without_traceview(env)
+          ensure
+            ::TraceView::API.log_exit('grape', report_kvs)
+          end
+        else
+          run_without_traceview(env)
+        end
+      end
+    end
+
+    module Middleware
+      module Error
+        def self.included(klass)
+          ::TraceView::Util.method_alias(klass, :error_response, ::Grape::Middleware::Error)
+        end
+
+        def error_response_with_traceview(error = {})
+          status, headers, body = error_response_without_traceview(error)
+
+          if TraceView.tracing?
+            # Since Grape uses throw/catch and not Exceptions, we manually log
+            # the error here.
+            kvs = {}
+            kvs[:ErrorClass] = 'GrapeError'
+            kvs[:ErrorMsg] = error[:message] ? error[:message] : "No message given."
+            kvs[:Backtrace] = ::TraceView::API.backtrace if TraceView::Config[:grape][:collect_backtraces]
+
+            ::TraceView::API.log(nil, 'error', kvs)
+
+            # Since calls to error() are handled similar to abort in Grape.  We
+            # manually log the rack exit here since the original code won't
+            # be returned to
+            xtrace = TraceView::API.log_end('rack', :Status => status)
+
+            if headers && TraceView::XTrace.valid?(xtrace)
+              unless defined?(JRUBY_VERSION) && TraceView.is_continued_trace?
+                headers['X-Trace'] = xtrace if headers.is_a?(Hash)
+              end
+            end
+          end
+
+          [status, headers, body]
+        end
+      end
+    end
+  end
+end
+
+if defined?(::Grape)
+  require 'traceview/inst/rack'
+
+  TraceView.logger.info "[traceview/loading] Instrumenting Grape" if TraceView::Config[:verbose]
+
+  TraceView::Loading.load_access_key
+  TraceView::Inst.load_instrumentation
+
+  ::TraceView::Util.send_extend(::Grape::API,               ::TraceView::Grape::API)
+  ::TraceView::Util.send_include(::Grape::Endpoint,          ::TraceView::Grape::Endpoint)
+  ::TraceView::Util.send_include(::Grape::Middleware::Error, ::TraceView::Grape::Middleware::Error)
+end
+