XRay 1.0.1 → 1.0.3

data/README

@@ -1,19 +1,44 @@
+= XRay
+
+* http://rubyforge.org/projects/xray
+
+== Description
+
 XRay provides a lightweight yet powerful toolbox for troubleshooting Ruby
-applications when things stop making sense. Includes GDB and DTrace tooling.
+applications when things stop making sense. XRay includes GDB and DTrace 
+tooling as well as a Thread Dump utility that can dump the stack trace 
+of all the thread in your Ruby VM when you send a +QUIT+ signal.
+
+== GDB
+
+Copy the +gdb_macros+ file provided in the gem as your ~/.gdbinit file.
+You will find more details on how to use them, in my
+{Troubleshooting Ruby Shortcut}[http://ph7spot.com/publications/troubleshooting_ruby_processes]
 
-*** GDB ***
+== Thread Dump
 
+After patching your Ruby VM with {caller_for_all_threads_patch_for_MRI_1.8.6.diff}[http://xray.rubyforge.org/svn/patches_for_mri/caller_for_all_threads_patch_for_MRI_1.8.6.diff]
+as explained in {this document}[http://ph7spot.com/caller_for_all_threads], you can install a signal
+handler in charge of dumping the stack trace for all the threads
+in your Ruby VM with:
 
-  Copy +gdb_macros+ file provided in the gem as your ~/.gdbinit file.
+  require "xray"
+  require "xray/thread_dump_signal_handler"
 
-*** Fire DTrace Application Probes ***
+You can then trigger a thread dump at any time with
 
-  See XRay::DTrace::Tracer
+  kill -QUIT <pid of your ruby process>
 
-*** Out-of-the-box Rails DTrace Instrumentation ***
+== DTrace
 
-  You are one require away from triggering automatically DTrace events for 
-  Rails requests, database access and template rendering. As simple as 
+=== 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|
@@ -25,10 +50,14 @@ applications when things stop making sense. Includes GDB and DTrace tooling.
        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
+See 
+* lib/xray/dtrace/railsenable_tracing.rb
+* lib/xray/dtrace/action_controller_tracing_extension.rb
+* lib/xray/dtrace/active_record_tracing_extension.rb
+
 
+== Author
 
+Philippe Hanrigou,
+http://ph7spot.com
 

data/Rakefile

@@ -0,0 +1,63 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/clean'
+require 'rubygems'
+
+CLEAN.include '**/*.o'
+CLEAN.include '**/*.so'
+CLEAN.include '**/*.bundle'
+CLOBBER.include '**/*.log'
+CLOBBER.include '**/Makefile'
+CLOBBER.include '**/extconf.h'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+
+desc 'Test XRay.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for XRay.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'XRay'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+specification = Gem::Specification.new do |s|
+  s.name = "XRay"
+  s.summary = "Dump backtrace for all threads."
+  s.version = "1.0.3"
+  s.author = "Philippe Hanrigou"
+	s.email = 'xray-developer@rubyforge.org'
+  s.homepage = "http://xray.rubyforge.com"
+  s.rubyforge_project = 'xray'
+  s.platform = Gem::Platform::RUBY
+  s.files = FileList['lib/**/*.rb'] + FileList['test/**/*.rb'] + 
+            FileList['**/*.d'] + FileList['**/*.diff'] + 
+            [ 'gdb_macros', 'Rakefile' ]
+  s.require_path = "lib"
+  s.extensions = []
+  s.rdoc_options << '--title' << 'XRay' << '--main' << 'README' << '--line-numbers'
+  s.has_rdoc = true
+  s.extra_rdoc_files = ['README']
+	s.test_file = "test/all_tests.rb"
+end
+  
+Rake::GemPackageTask.new(specification) do |package|
+	 package.need_zip = false
+	 package.need_tar = false
+end
+
+desc "Publish RDoc on Rubyforge website"
+task :publish_rdoc => :rdoc do
+  sh "scp -i ~/.ssh/id_dsa -r rdoc/* #{ENV['USER']}@rubyforge.org:/var/www/gforge-projects/xray"
+end

data/lib/xray/thread_dump_signal_handler.rb

@@ -0,0 +1,31 @@
+#
+# Install a signal handler to dump backtraces for all threads
+#
+# Trigger it with: kill -QUIT <pid>
+#  
+trap "QUIT" do
+  if Kernel.respond_to? :caller_for_all_threads
+    STDERR.puts "\n=============== XRay - Thread Dump ==============="
+    caller_for_all_threads.each_pair do |thread, stack|
+      thread_description = thread.inspect
+      thread_description << " [main]" if thread == Thread.main
+      thread_description << " [current]" if thread == Thread.current
+      thread_description << " alive=#{thread.alive?}"
+      thread_description << " priority=#{thread.priority}"
+      thread_separator = "-" * 78
+      
+      full_description = "\n#{thread_separator}\n"
+      full_description << thread_description
+      full_description << "\n#{thread_separator}\n"
+      full_description << "    #{stack.join("\n      \\_ ")}\n"
+      
+      # Single puts to avoid interleaved output
+      STDERR.puts full_description
+    end
+  else
+    STDERR.puts "=============== XRay - Current Thread Backtrace ==============="
+    STDERR.puts "Current thread : #{Thread.inspect}"
+    STDERR.puts caller.join("\n    \\_ ")
+  end
+  STDERR.puts "\n=============== XRay - Done ===============\n"
+end

data/patches_for_mri/caller_for_all_threads_patch_for_MRI_1.8.6.diff

@@ -0,0 +1,229 @@
+Index: test/callerforallthreads/test_caller_for_each_thread.rb
+===================================================================
+--- test/callerforallthreads/test_caller_for_each_thread.rb	(revision 0)
++++ test/callerforallthreads/test_caller_for_each_thread.rb	(revision 0)
+@@ -0,0 +1,95 @@
++# -*- ruby-indent-level: 4 -*-
++require 'thread'
++require 'test/unit'
++
++class AClassWithNestedmethods
++  
++  def an_ultra_nested_method(skip)
++    caller_for_all_threads skip
++  end
++
++  def a_nested_method(skip)
++    an_ultra_nested_method skip
++  end
++
++  def a_method(skip=0)
++    a_nested_method skip
++  end
++  
++end
++
++class CallerForEachThreadTest < Test::Unit::TestCase
++  
++  def testCollectMeaningfulBacktraceForASingleThread
++    backtraces = AClassWithNestedmethods.new.a_method
++    backtrace = backtraces[Thread.current]
++    assert_not_nil backtrace
++    assert_equal __FILE__ + ":8:in `an_ultra_nested_method'", backtrace[0]
++    assert_equal __FILE__ + ":12:in `a_nested_method'", backtrace[1]
++    assert_equal __FILE__ + ":16:in `a_method'", backtrace[2]
++    assert_equal __FILE__ + ":24:in `testCollectMeaningfulBacktraceForASingleThread'", 
++                 backtrace[3]
++  end
++
++  def testCanSkipFirstStackEntries
++    backtraces = AClassWithNestedmethods.new.a_method 2
++    backtrace = backtraces[Thread.current]
++    assert_not_nil backtrace
++    assert_equal __FILE__ + ":16:in `a_method'", backtrace[0]
++    assert_equal __FILE__ + ":35:in `testCanSkipFirstStackEntries'", 
++                 backtrace[1]
++  end
++
++  def testCollectMeaningfulBacktraceForMultipleThreads
++    first_thread = Thread.new do
++      loop do
++        Thread.pass
++        sleep 1
++      end
++    end
++
++    second_thread = Thread.new do
++      loop do
++        Thread.pass
++        sleep 1
++      end
++    end
++
++    backtraces = AClassWithNestedmethods.new.a_method
++    
++    backtrace = backtraces[Thread.current]
++    assert_not_nil backtrace
++    assert_match __FILE__ + ":8:in `an_ultra_nested_method'", backtrace[0]
++    assert_match __FILE__ + ":12:in `a_nested_method'", backtrace[1]
++    assert_equal __FILE__ + ":16:in `a_method'", backtrace[2]
++    assert_equal __FILE__ + ":58:in `testCollectMeaningfulBacktraceForMultipleThreads'", 
++                 backtrace[3]
++                 
++    backtrace = backtraces[first_thread]
++    assert_not_nil backtrace
++    assert_equal __FILE__ + ":47:in `testCollectMeaningfulBacktraceForMultipleThreads'", 
++                 backtrace[0]
++    assert_equal __FILE__ + ":45:in `loop'", 
++                 backtrace[1]
++    assert_equal __FILE__ + ":45:in `testCollectMeaningfulBacktraceForMultipleThreads'",
++                 backtrace[2]
++    assert_equal __FILE__ + ":44:in `initialize'",backtrace[3]
++    assert_equal __FILE__ + ":44:in `new'", backtrace[4]
++    assert_equal __FILE__ + ":44:in `testCollectMeaningfulBacktraceForMultipleThreads'",
++                 backtrace[5]
++
++    backtrace = backtraces[second_thread]
++    assert_not_nil backtrace
++    assert_equal __FILE__ + ":53:in `testCollectMeaningfulBacktraceForMultipleThreads'", 
++                 backtrace[0]
++    assert_equal __FILE__ + ":52:in `loop'", backtrace[1]
++    assert_equal __FILE__ + ":52:in `testCollectMeaningfulBacktraceForMultipleThreads'",
++                 backtrace[2]
++    assert_equal __FILE__ + ":51:in `initialize'",backtrace[3]
++    assert_equal __FILE__ + ":51:in `new'", backtrace[4]
++    assert_equal __FILE__ + ":51:in `testCollectMeaningfulBacktraceForMultipleThreads'",
++                 backtrace[5]
++  end
++  
++end
++
+Index: eval.c
+===================================================================
+--- eval.c	(revision 16289)
++++ eval.c	(working copy)
+@@ -7969,6 +7969,17 @@
+     ruby_safe_level = safe;
+ }
+ 
++/* Hash (Thread => Backtrace) used to collect backtrace for each threads. */
++static VALUE backtrace_for_each_thread;
++
++static int backtrace_level_for_each_thread;
++
++static VALUE
++switch_thread_context_to_collect_backtrace(rb_thread_t next);
++
++static VALUE
++rb_f_caller_for_all_threads();
++
+ void
+ Init_eval()
+ {
+@@ -8014,6 +8025,7 @@
+     rb_define_global_function("fail", rb_f_raise, -1);
+ 
+     rb_define_global_function("caller", rb_f_caller, -1);
++    rb_define_global_function("caller_for_all_threads", rb_f_caller_for_all_threads, -1);
+ 
+     rb_define_global_function("exit", rb_f_exit, -1);
+     rb_define_global_function("abort", rb_f_abort, -1);
+@@ -10206,6 +10218,7 @@
+ #define RESTORE_RAISE		5
+ #define RESTORE_SIGNAL		6
+ #define RESTORE_EXIT		7
++#define RESTORE_BACKTRACE	8
+ 
+ extern VALUE *rb_gc_stack_start;
+ #ifdef __ia64
+@@ -10313,6 +10326,15 @@
+ 	}
+ 	rb_exc_raise(th_raise_exception);
+ 	break;
++      case RESTORE_BACKTRACE:
++        rb_hash_aset(backtrace_for_each_thread, curr_thread->thread, 
++                     backtrace(backtrace_level_for_each_thread));
++        if (curr_thread != main_thread) {
++            switch_thread_context_to_collect_backtrace(curr_thread->next);
++        } else { 
++	        /* Circled back to main thread, cycle is complete. */
++        }
++        break;
+       case RESTORE_NORMAL:
+       default:
+ 	break;
+@@ -13240,3 +13262,74 @@
+     argv[1] = val;
+     rb_f_throw(2, argv);
+ }
++
++static VALUE
++switch_thread_context_to_collect_backtrace(rb_thread_t next)
++{
++    if (THREAD_SAVE_CONTEXT(curr_thread)) {
++        return Qnil;
++    }
++    curr_thread = next;
++    rb_thread_restore_context(next, RESTORE_BACKTRACE);
++    return Qnil;
++}
++
++
++/*
++ *  call-seq:
++ *     caller_for_all_threads(start=1)    => array
++ *  
++ *  Returns the current execution stack for all threads 
++ *  ---a hash whose keys are thread instances and values
++ *  the thread caller backtrace.
++ *
++ *  Backtraces are array of hashes indicating location on the 
++ *  stack. Hash keys include ``<em>:line</em>'' or ``<em>:file</em>''
++ *  and ``<em>:method'</em>''. 
++ *
++ *  The optional _start_ parameter
++ *  determines the number of initial stack entries to omit from the
++ *  result.
++ *     
++ *     def a(skip)
++ *       caller_for_all_threads(skip)
++ *     end
++ *     def b(skip)
++ *       a(skip)
++ *     end
++ *     def c(skip)
++ *       b(skip)
++ *     end
++ *     c(0)   #=> ["prog:2:in `a'", "prog:5:in `b'", "prog:8:in `c'", "prog:10"]
++ *     c(1)   #=> ["prog:5:in `b'", "prog:8:in `c'", "prog:11"]
++ *     c(2)   #=> ["prog:8:in `c'", "prog:12"]
++ *     c(3)   #=> ["prog:13"]
++ */
++static VALUE
++rb_f_caller_for_all_threads(argc, argv)
++    int argc;
++    VALUE *argv;
++{
++    volatile int critical;
++    VALUE level;
++	VALUE result;
++
++    rb_scan_args(argc, argv, "01", &level);
++    backtrace_level_for_each_thread = NIL_P(level) ? 0 : NUM2INT(level);
++	if (backtrace_level_for_each_thread < 0) {
++		rb_raise(rb_eArgError, "negative level (%d)", backtrace_level_for_each_thread);
++	}
++
++	critical = rb_thread_critical;
++	rb_thread_critical = Qtrue;
++
++    backtrace_for_each_thread = rb_hash_new();
++    switch_thread_context_to_collect_backtrace(main_thread->next);
++
++	result = backtrace_for_each_thread;
++	backtrace_for_each_thread = Qnil;
++	backtrace_for_each_thread = 0;
++		
++	rb_thread_critical = critical;
++    return result;
++}

data/{patch-for-dtrace-instrumentation-of-matz-1.8.6-p114.diff → patches_for_mri/patch-for-dtrace-instrumentation-of-matz-1.8.6-p114.diff}

@@ -131,7 +131,7 @@ Index: tracer.c
 ===================================================================
 --- tracer.c	(revision 0)
 +++ tracer.c	(revision 0)
-@@ -0,0 +1,62 @@
+@@ -0,0 +1,73 @@
 +#include "ruby.h"
 +
 +#ifdef ENABLE_DTRACE
@@ -188,11 +188,22 @@ Index: tracer.c
 +    	return ret;
 +}
 +
++static VALUE
++ruby_dtrace_enabled(klass)
++    VALUE klass;
++{
++#ifdef ENABLE_DTRACE
++    return RUBY_RUBY_PROBE_ENABLED() ? Qtrue : Qfalse;
++#else
++    return Qfalse;
++#endif
++}
 +
 +void Init_Tracer()
 +{
 +	rb_mDtrace = rb_define_module("Tracer");
 +	rb_define_module_function(rb_mDtrace, "fire", ruby_dtrace_fire, -1);
++	rb_define_module_function(rb_mDtrace, "enabled?", ruby_dtrace_enabled, 0);
 +}
 Index: dtrace.d
 ===================================================================
@@ -225,7 +236,7 @@ Index: dtrace.d
 +#pragma D attributes Private/Private/Common provider ruby function
 +#pragma D attributes Evolving/Evolving/Common provider ruby name
 +#pragma D attributes Evolving/Evolving/Common provider ruby args
-
++
 Index: common.mk
 ===================================================================
 --- common.mk	(revision 16089)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: XRay
 version: !ruby/object:Gem::Version 
-  version: 1.0.1
+  version: 1.0.3
 platform: ruby
 authors: 
 - Philippe Hanrigou
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-04-20 00:00:00 -07:00
+date: 2008-05-29 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -27,8 +27,8 @@ files:
 - 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/thread_aware_dispatcher.rb
+- lib/xray/thread_dump_signal_handler.rb
 - lib/xray/xray.rb
 - test/all_tests.rb
 - test/functional/dtrace/tracer_test.rb
@@ -37,9 +37,11 @@ files:
 - test/unit/thread_aware_dispatcher_test.rb
 - test/unit/xray/dtrace/tracer_test.rb
 - application-probes.d
-- patch-for-dtrace-instrumentation-of-matz-1.8.6-p114.diff
-- patch-for-joyent-mri-1.8.6-on-leopard.diff
+- patches_for_mri/caller_for_all_threads_patch_for_MRI_1.8.6.diff
+- patches_for_mri/patch-for-dtrace-instrumentation-of-matz-1.8.6-p114.diff
+- patches_for_mri/patch-for-joyent-mri-1.8.6-on-mac-os-x-leopard.diff
 - gdb_macros
+- Rakefile
 - README
 has_rdoc: true
 homepage: http://xray.rubyforge.com

data/lib/xray/rails_stack_signal_handler.rb

@@ -1,15 +0,0 @@
-#
-# 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