traceview 3.0.0

data/lib/traceview/api/memcache.rb

@@ -0,0 +1,31 @@
+# Copyright (c) 2013 AppNeta, Inc.
+# All rights reserved.
+
+module TraceView
+  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)
+        if server_as_array.is_a?(Array)
+          server = server_as_array.first
+          if is_unix_socket?(server)
+            return 'localhost'
+          elsif defined?(server.hostname)
+            return server.hostname
+          end
+        end
+      end
+    end
+  end
+end

data/lib/traceview/api/profiling.rb

@@ -0,0 +1,50 @@
+# Copyright (c) 2013 AppNeta, Inc.
+# All rights reserved.
+
+module TraceView
+  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)
+      #     TraceView::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)
+        report_kvs[:Language] ||= :ruby
+        report_kvs[:ProfileName] ||= profile_name
+        report_kvs[:Backtrace] = TraceView::API.backtrace if with_backtrace
+
+        TraceView::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]
+
+          TraceView::API.log(nil, 'profile_exit', exit_kvs)
+        end
+      end
+    end
+  end
+end

data/lib/traceview/api/tracing.rb

@@ -0,0 +1,135 @@
+# Copyright (c) 2013 AppNeta, Inc.
+# All rights reserved.
+
+module TraceView
+  module API
+    ##
+    # Provides the higher-level tracing interface for the API.
+    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 - specify the operation being traced.  Used to avoid
+      # double tracing between operations that call each other
+      #
+      # Example
+      #
+      #   def computation(n)
+      #     fib(n)
+      #     raise Exception.new
+      #   end
+      #
+      #   def computation_with_oboe(n)
+      #     trace('fib', { :number => n }) 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, {}, protect_op)
+        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. Insert the oboe metadata into the provided for
+      # later user.
+      #
+      # 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.
+      # target - The target object in which to place the oboe metadata.
+      # 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 = TraceView::Context.createEvent
+        begin
+          target['X-Trace'] = TraceView::Event.metadataString(exit_evt) if TraceView.tracing?
+          yield
+        rescue Exception => e
+          log_exception(layer, e)
+          raise
+        ensure
+          exit_evt.addEdge(TraceView::Context.get)
+          log_event(layer, 'exit', exit_evt)
+          TraceView::Context.clear
+        end
+      end
+    end
+  end
+end

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/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