XRay 1.0

data/README

@@ -0,0 +1,34 @@
+XRay provides a lightweight yet powerful toolbox for troubleshooting Ruby
+applications when things stop making sense. Includes GDB and DTrace tooling.
+
+*** GDB ***
+
+
+  Copy +gdb_macros+ file provided in the gem as your ~/.gdbinit file.
+
+*** Fire DTrace Application Probes ***
+
+  See XRay::DTrace::Tracer
+
+*** Out-of-the-box Rails DTrace Instrumentation ***
+
+  You are one require away from triggering automatically DTrace events for 
+  Rails requests, database access and template rendering. As simple as 
+
+     # environment.rb
+     Rails::Initializer.run do |config|
+
+       ...
+
+       config.after_initialize do
+         require "xray/dtrace/rails/enable_tracing"
+       end  
+     end
+ 
+  See 
+   * lib/xray/dtrace/railsenable_tracing.rb
+   * lib/xray/dtrace/action_controller_tracing_extension.rb
+   * lib/xray/dtrace/active_record_tracing_extension.rb
+
+
+

data/lib/xray/dtrace/rails/action_controller_tracing_extension.rb

@@ -0,0 +1,22 @@
+#
+# Decorate ActionController::Base with request tracing
+#
+ActionController::Base.class_eval do
+  include XRay::DTrace::Tracer
+  
+  def perform_action_with_tracing
+    firing('request', "#{self.class.to_s}##{action_name.to_s}") do
+       perform_action_without_tracing
+    end
+  end
+      
+  def render_with_tracing(options = nil, deprecated_status = nil, &block)
+    firing('render', options.to_s) do
+       render_without_tracing options, deprecated_status
+    end
+  end
+
+  alias_method_chain :perform_action, :tracing
+  alias_method_chain :render, :tracing
+          
+end

data/lib/xray/dtrace/rails/active_record_connection_tracing_extension.rb

@@ -0,0 +1,15 @@
+#
+# Decorate ActiveRecord connection with DB tracing
+#
+ActiveRecord::Base.connection.class.class_eval do
+  include XRay::DTrace::Tracer
+
+  def execute_with_tracing(sql, name=nil)
+    firing('db', sql) do
+       execute_without_tracing sql, name
+    end
+  end
+  
+  alias_method_chain :execute, :tracing
+
+end

data/lib/xray/dtrace/rails/enable_tracing.rb

@@ -0,0 +1,25 @@
+# Require this file to enable out the box DTrace tracing 
+# for your Rails application
+#
+# You typically change your environment.rb to require it after config
+# initialization:
+#
+#   Rails::Initializer.run do |config|
+#
+#     ...
+#
+#     config.after_initialize do
+#       require "xray/dtrace/rails/enable_tracing"
+#     end  
+#   end
+
+require 'xray/dtrace/tracer'
+if Object.const_defined? :ActionController
+  puts "Enabling controller tracing"
+  require "xray/dtrace/rails/action_controller_tracing_extension"
+end
+
+if Object.const_defined? :ActiveRecord
+  puts "Enabling DB tracing"
+  require "xray/dtrace/rails/active_record_connection_tracing_extension"
+end

data/lib/xray/dtrace/tracer.rb

@@ -0,0 +1,111 @@
+module XRay
+  module DTrace
+    
+    # Ruby module to fire application-level Dtrace events (using ruby-probe).
+    # 
+    # This module provide a convenient and unified API abstracting 
+    # different tracing implementations in Leopard Ruby VM (by Apple) 
+    # and in the one provided by Joyent (https://dev.joyent.com/projects/ruby-dtrace). 
+    # This module also provides a NOOP implementation for Ruby VMs with 
+    # no DTrace support: So you can use the exact same code while developing
+    # on Linux and deploying on Solaris for instance.
+    module Tracer
+      
+      if Object.const_defined?(:DTracer)    ### Leopard tracer ###
+
+        # Fire an application-level probe using ruby-probe.
+        #   
+        # The first argument passed will be passed to the D script as arg0 for
+        # the ruby-probe probe. This is conventionally a probe name.
+        #   
+        # The second argument is optional and can be used to pass additional
+        # data into the D script as arg1.
+        #
+        # Example:
+        #   
+        # XRay::DTrace::Tracer.fire('service-start', "order processing")
+        #
+        # XRay::DTrace::Tracer.fire('service-stop')
+        #
+        def fire(name, data = nil)
+          DTracer.fire(name, data)
+        end
+
+        # Use ruby-probe to fire 2 application-level probes before and after
+        # evaling a block .
+        #    
+        # The first argument passed will be passed to the D script as arg0 for
+        # the ruby-probe probe. This is conventionally a probe base name. The
+        # probes which fire before and after the block runs will have
+        # "-start" and "-end" appended, respectively.
+        #    
+        # The second argument is optional and can be used to pass additional
+        # data into the D script as arg1.
+        #
+        # Example:
+        #    
+        # XRay::DTrace::Tracer.fire('service-start', "order processing")
+        #
+        # XRay::DTrace::Tracer.firing('db-query', "select * from dual;") do
+        #   ActiveRecord::Base.execute("select * from dual;")
+        # 
+        # end
+        #
+        # Will:
+        # 1. Fire a probe with arg0 set to "db-query-start", and arg1 set
+        #    to the sql query.
+        # 
+        # 2. Run the block and execute the SQL.
+        #
+        # 3. Fire a probe with arg0 set to "db-query-start".    
+        def firing(name, data = nil)
+          fire(name + "-start", data)
+          result = yield
+          fire(name + "-end", data)
+          result
+        end
+
+        # Returns true if ruby-probe probes are enables 
+        # (application-level probes for Ruby).
+        def enabled?
+          DTracer.enabled?
+        end
+
+     
+      elsif Object.const_defined?(:Tracer) && Tracer.methods.include?(:fire)  ### Joyent Tracer ##
+
+        raise "got here"
+
+        def fire(name, data = nil)    #:nodoc: all      
+        
+          ::Tracer.fire(name, data)
+        end
+
+        def firing(name, data = nil) #:nodoc: all      
+          ::Tracer.fire(name, data)
+        end
+        
+        def enabled?  #:nodoc: all      
+          STDERR.puts "WARNING: XRay::DTrace.Tracer.enabled? does not work with Joyent Tracer"
+          false
+        end
+        
+      else                                ### No ruby-probe support ###
+
+        def fire(name, data = nil) #:nodoc: all      
+        end
+
+        def firing(name, data = nil) #:nodoc: all      
+          yield
+        end
+
+        def enabled?  #:nodoc: all      
+          false
+        end
+        
+      end
+    
+      end
+    
+  end
+end

data/lib/xray/enable_thread_aware_dispatcher.rb

@@ -0,0 +1 @@
+Dispatcher.send :include, XRay::ThreadAwareDispatcher

data/lib/xray/rails_stack_signal_handler.rb

@@ -0,0 +1,15 @@
+#
+# Install a signal handler dumping Rails stack by raising an exception
+#
+# Trigger it with: kill -QUIT <pid>
+#  
+
+trap "QUIT" do
+  STDERR.puts "=============== XRay - Raising exception in Rails thread ==============="
+  if Dispatcher.thread_in_dispatch
+    Dispatcher.thread_in_dispatch.raise "XRay - Forced exception to Rails stack trace"
+  else
+    STDERR.puts "No Rails thread in dispatch"
+  end
+  STDERR.puts "=============== XRay - Done ==============="
+end

data/lib/xray/signal_handler.rb

@@ -0,0 +1,26 @@
+#
+# Install a signal handler dumping current thread stack
+#
+# Trigger it with: kill -QUIT <pid>
+#
+module XRay
+  
+  def self.dump_threads
+    STDERR.puts "=============== XRay Inspector ==============="
+    STDERR.puts "Current Thread\n    "
+    STDERR.puts caller.join("\n    \_ ")
+    STDERR.puts Thread.current.xray_backtrace.join("\n    \_ ")
+    # STDERR.puts "----------------------------------------------"
+    # Thread.list.each_with_index do |t,i| 
+    #   STDERR.puts "Dumping Thread #{i}\n    "
+    #   t.xray_backtrace.join("\n    \_ ")
+    # end
+    STDERR.puts "=============================================="
+    STDERR.flush
+  end
+  
+end
+
+trap "QUIT" do
+  XRay.dump_threads
+end

data/lib/xray/thread_aware_dispatcher.rb

@@ -0,0 +1,27 @@
+module XRay
+  
+  module ThreadAwareDispatcher
+
+    # Intercept dispatch with our own method when the module is included.
+    def self.included(target)
+      class << target
+        attr_reader :thread_in_dispatch
+
+        alias actual_dispatch dispatch
+  
+        # Capture as an instance variable the current 
+        # thread -- which is processing current Rails request --
+        # and do the actual dispatch. 
+        def dispatch(*args)
+          @thread_in_dispatch = Thread.current
+          actual_dispatch *args
+        ensure
+          @thread_in_dispatch = nil
+        end
+  
+      end
+    end
+  
+  end
+  
+end

data/lib/xray/xray.rb

@@ -0,0 +1 @@
+require 'xray/thread_aware_dispatcher'

data/test/all_tests.rb

@@ -0,0 +1 @@
+Dir["#{File.dirname __FILE__}/**/*_test.rb"].each { |test_case| require test_case }

data/test/functional/dtrace/tracer_test.rb

@@ -0,0 +1,54 @@
+require File.expand_path(__FILE__ + '/../../../test_helper')
+
+functional_tests do
+
+  test "fire a probe with no data and no block" do
+    aClass = Class.new do
+      include XRay::DTrace::Tracer
+    end
+
+    aClass.new.fire "a name"
+  end
+
+  test "fire a probe with data and no block" do
+    aClass = Class.new do
+      include XRay::DTrace::Tracer
+    end
+
+    aClass.new.fire "a name", "some data"
+  end
+
+  test "Can check whether ruby-probe is enabled" do
+    aClass = Class.new do
+      include XRay::DTrace::Tracer
+    end
+
+    assert [true, false].include?(aClass.new.enabled?)
+  end
+
+  test "fire a probe with block and no data" do
+    anObject = Class.new do
+      include XRay::DTrace::Tracer
+    end.new
+  
+    result = anObject.firing("a-name") do
+      :expected_result
+    end
+  
+    assert_equal :expected_result, result
+  end
+  
+  test "fire a probe with block and data" do
+    anObject = Class.new do
+      include XRay::DTrace::Tracer
+    end.new
+  
+    result = anObject.firing("a-name", "some data") do
+      :expected_result
+    end
+  
+    assert_equal :expected_result, result
+  end
+  
+end
+

data/test/functional/tracer_script.rb

@@ -0,0 +1,18 @@
+$: << File.dirname(__FILE__) + '/../../lib'
+require 'xray/dtrace/tracer'
+
+class Service
+  include XRay::DTrace::Tracer
+  
+  def process
+    puts "Processing new request"
+    firing "my-service", "a sql query" do
+      sleep 2
+    end
+  end
+  
+end
+
+loop do
+  Service.new.process
+end

data/test/test_helper.rb

@@ -0,0 +1,10 @@
+$: << File.dirname(__FILE__) + '/../ext/xray'
+$: << File.dirname(__FILE__) + '/../lib'
+require 'xray/xray'
+require 'xray/dtrace/tracer'
+
+require 'test/unit'
+require 'rubygems'
+require 'mocha'
+require 'dust'
+

data/test/unit/thread_aware_dispatcher_test.rb

@@ -0,0 +1,51 @@
+require File.expand_path(__FILE__ + '/../../test_helper')
+
+unit_tests do
+
+  test "thread aware dispatcher returns original dispath result" do
+    dispatcher = Class.new
+    dispatcher.expects(:dispatch).with(:the_args).returns(:the_result)
+    dispatcher.send :include, XRay::ThreadAwareDispatcher
+    dispatcher.dispatch(:the_args)
+  end
+
+  test "thread aware dispatcher adds accessor for thread in dispatch" do
+    dispatcher = Class.new
+    dispatcher.stubs(:dispatch)
+    dispatcher.send :include, XRay::ThreadAwareDispatcher
+    dispatcher.thread_in_dispatch
+  end
+
+  test "thread in dispatch is nil when not in dispatch" do
+    dispatcher = Class.new
+    dispatcher.stubs(:dispatch)
+    dispatcher.send :include, XRay::ThreadAwareDispatcher
+    assert_nil dispatcher.thread_in_dispatch
+  end
+
+  test "thread in dispatch is nil when dispatch raises" do
+    begin
+      dispatcher = Class.new
+      dispatcher.expects(:dispatch).raises(StandardError.new("Fake Problem"))
+      dispatcher.send :include, XRay::ThreadAwareDispatcher
+      dispatcher.dispatch
+      flunk "Should relay exception"
+    rescue StandardError
+      assert_nil dispatcher.thread_in_dispatch
+    end
+  end
+
+  test "thread in dispatch is set to current thread when in dispatch" do
+    dispatcher = Class.new do
+      extend Test::Unit::Assertions
+
+      def self.dispatch(*args)
+        assert_equal Thread.current, thread_in_dispatch 
+      end
+
+      include XRay::ThreadAwareDispatcher
+    end
+    dispatcher.dispatch
+  end
+
+end

data/test/unit/xray/dtrace/tracer_test.rb

@@ -0,0 +1,54 @@
+require File.expand_path(__FILE__ + '/../../../../test_helper')
+
+unit_tests do
+
+  test "fire a probe with no data and no block" do
+    aClass = Class.new do
+      include XRay::DTrace::Tracer
+    end
+
+    aClass.new.fire "a name"
+  end
+
+  test "fire a probe with data and no block" do
+    aClass = Class.new do
+      include XRay::DTrace::Tracer
+    end
+
+    aClass.new.fire "a name", "some data"
+  end
+
+  test "Can check whether ruby-probe is enabled" do
+    aClass = Class.new do
+      include XRay::DTrace::Tracer
+    end
+
+    assert [true, false].include?(aClass.new.enabled?)
+  end
+
+  test "fire a probe with block and no data" do
+    anObject = Class.new do
+      include XRay::DTrace::Tracer
+    end.new
+  
+    result = anObject.firing("a-name") do
+      :expected_result
+    end
+  
+    assert_equal :expected_result, result
+  end
+  
+  test "fire a probe with block and data" do
+    anObject = Class.new do
+      include XRay::DTrace::Tracer
+    end.new
+  
+    result = anObject.firing("a-name", "some data") do
+      :expected_result
+    end
+  
+    assert_equal :expected_result, result
+  end
+  
+end
+

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification 
+name: XRay
+version: !ruby/object:Gem::Version 
+  version: "1.0"
+platform: ruby
+authors: 
+- Philippe Hanrigou
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-03-28 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: 
+email: xray-developer@rubyforge.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- lib/xray/dtrace/rails/action_controller_tracing_extension.rb
+- lib/xray/dtrace/rails/active_record_connection_tracing_extension.rb
+- lib/xray/dtrace/rails/enable_tracing.rb
+- lib/xray/dtrace/tracer.rb
+- lib/xray/enable_thread_aware_dispatcher.rb
+- lib/xray/rails_stack_signal_handler.rb
+- lib/xray/signal_handler.rb
+- lib/xray/thread_aware_dispatcher.rb
+- lib/xray/xray.rb
+- test/all_tests.rb
+- test/functional/dtrace/tracer_test.rb
+- test/functional/tracer_script.rb
+- test/test_helper.rb
+- test/unit/thread_aware_dispatcher_test.rb
+- test/unit/xray/dtrace/tracer_test.rb
+- README
+has_rdoc: true
+homepage: http://xray.rubyforge.com
+post_install_message: 
+rdoc_options: 
+- --title
+- XRay
+- --main
+- README
+- --line-numbers
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: xray
+rubygems_version: 1.0.1
+signing_key: 
+specification_version: 2
+summary: Dump backtrace for all threads.
+test_files: 
+- test/all_tests.rb