xray 1.1

data/README

@@ -0,0 +1,65 @@
+= XRay
+
+* http://rubyforge.org/projects/xray
+
+== Description
+
+XRay provides a lightweight yet powerful toolbox for troubleshooting Ruby
+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]
+
+== 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]
+(or {caller_for_all_threads_patch_for_MRI_1.8.7.diff}[http://xray.rubyforge.org/svn/patches_for_mri/caller_for_all_threads_patch_for_MRI_1.8.7.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:
+
+  require "rubygems"
+  require "xray/thread_dump_signal_handler"
+
+You can then trigger a thread dump at any time with
+
+  kill -QUIT <pid of your ruby process>
+
+== DTrace
+
+=== 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 "rubygems"
+         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
+
+
+== Author
+
+Philippe Hanrigou,
+http://ph7spot.com
+

data/bin/install_dtrace_on_ubuntu

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+#
+# Painless DTrace install for Ubuntu
+#
+
+DISTRIBUTION=dtrace-20081028
+
+download()
+{
+    sudo apt-get install curl
+    if [ ! -e ${DISTRIBUTION} ]; then
+        echo "\n==== Downloading DTrace for Linux ====\n"
+        curl -O ftp://crisp.dynalias.com/pub/release/website/dtrace/${DISTRIBUTION}.tar.bz2
+        tar jxvf ${DISTRIBUTION}.tar.bz2
+    fi
+}
+
+install_dependencies()
+{
+    sudo apt-get install zlib1g-dev flex bison elfutils libelf-dev libc6-dev linux-libc-dev
+}
+
+build()
+{
+    make -C ${DISTRIBUTION} clean all
+}
+
+download
+install_dependencies
+build

data/bin/xray_profile_ruby_function_calls.d

@@ -0,0 +1,54 @@
+#!/usr/sbin/dtrace -s 
+#pragma D option quiet
+#pragma D option aggsortrev
+#pragma D option dynvarsize=64m
+
+/* 
+ * Trace all ruby function calls and display their total time, average time
+ * an invocation number (slower first).
+ *
+ * Usage:
+ *
+ *     sudo /usr/bin/xray_profile_ruby_function_calls.d -p <a pid>
+ *
+ *     sudo /usr/bin/xray_profile_ruby_function_calls.d -c "ruby -v"
+ *
+ *     sudo dtrace -s /usr/bin/xray_profile_ruby_function_calls.d -p <a pid>
+ */
+ 
+this string str;
+
+dtrace:::BEGIN
+{
+   printf("Tracing, please be patient... Ctrl-C to interrupt.\n");
+   depth = 0;
+}
+
+ruby$target:::function-entry
+{
+   self->depth++;
+   self->start[copyinstr(arg0), copyinstr(arg1), self->depth] = timestamp;
+}
+
+ruby$target:::function-return
+/(this->class = copyinstr(arg0)) != NULL && \
+ (this->func  = copyinstr(arg1)) != NULL && \
+ self->start[this->class, this->func, self->depth]/
+{
+    this->elapsed = timestamp - self->start[this->class, this->func, self->depth];
+    @num[this->class, this->func] = count();
+    @eavg[this->class, this->func] = avg(this->elapsed);
+    @esum[this->class, this->func] = sum(this->elapsed);
+    self->start[this->class, this->func, self->depth] = 0;
+    self->depth--;
+}
+
+dtrace:::END
+{
+    normalize(@eavg, 1000);
+    normalize(@esum, 1000);
+    setopt("aggsortpos", "0");   /* Sort on total time */
+    printf("%95s\n", "_______ ELAPSED ______");
+    printf("%-40s %-30s %12s %10s %6s\n", "Class", "Method", "Total (us)", "Avg (us)", "Count\n");
+    printa("%-40.40s %-30.30s %@12d %@10d %@6d\n", @esum, @eavg, @num);
+}

data/bin/xray_top_10_busiest_code_path_for_process.d

@@ -0,0 +1,12 @@
+#!/usr/sbin/dtrace -s
+#pragma D option quiet
+#pragma D option aggsortrev
+#pragma D option dynvarsize=64m
+#pragma D option ustackframes=64
+#pragma D option strsize=2048
+
+profile-997
+/pid == $target/ 
+{ 
+    @num[ustack()] = count(); 
+}

data/bin/xray_top_10_busiest_code_path_on_system.d

@@ -0,0 +1,35 @@
+#!/usr/sbin/dtrace -s
+#pragma D option quiet
+#pragma D option dynvarsize=64m
+
+dtrace:::BEGIN 
+{
+    printf("Tracing... Hit Ctrl-C to end.\n");
+    depth = 0;
+}
+
+
+profile-997 
+{
+    @kernel[stack(20)]=count();
+}
+
+
+
+profile-997 
+/arg1/       /* user level PC. Make sure that we are in user space */
+{
+    printf("%d\n", arg1);
+    @userspace[execname, ustack(10)]=count();
+}
+
+END {
+    trunc(@kernel, 10);
+    trunc(@userspace, 10); 
+    
+    printf("%s", "\n =========== Top 10 Busiest Kernel Path =============\n");
+    printa(@kernel);
+    
+     printf("%s", "\n =========== Top 10 Busiest User Path =============\n");
+     printa(@userspace);
+}

data/bin/xray_trace_all_custom_ruby_probes.d

@@ -0,0 +1,25 @@
+#!/usr/sbin/dtrace -s 
+#pragma D option quiet
+
+/*
+ * Trace all the custom ruby probes defined in your application
+ * using XRay::DTrace, Apple's DTracer or Joyent's Tracer module.
+ *
+ * Usage:
+ *
+ *     sudo /usr/bin/xray_trace_all_custom_ruby_probes.d -p <a pid>
+ *
+ *     sudo /usr/bin/xray_trace_all_custom_ruby_probes.d -c "ruby -v"
+ *
+ *     sudo dtrace -s /usr/bin/xray_trace_all_custom_ruby_probes.d -p <a pid>
+ */
+
+dtrace:::BEGIN
+{
+    printf("Tracing... Hit Ctrl-C to end.\n");
+}
+
+ruby$target:::ruby-probe
+{
+	printf("=> %d == cpu: %2d == %15s '%s'\n", timestamp, cpu, copyinstr(arg0), copyinstr(arg1))
+}

data/bin/xray_trace_all_ruby_probes.d

@@ -0,0 +1,20 @@
+#!/usr/sbin/dtrace -s 
+#pragma D option quiet
+#pragma D option dynvarsize=64m
+
+/*
+ * Trace all the probes of the ruby provider
+ *
+ * Usage:
+ *
+ *     sudo /usr/bin/xray_trace_all_ruby_probes.d -p <a pid>
+ *
+ *     sudo /usr/bin/xray_trace_all_ruby_probes.d -c "ruby -v"
+ *
+ *     sudo dtrace -s /usr/bin/xray_trace_all_ruby_probes.d -p <a pid>
+ */
+
+ruby$target::: 
+{ 
+    printf("=> cpu %2d == %-15.15s == %-15.15s == %s\n", cpu, probename, copyinstr(arg0), copyinstr(arg1)) 
+}

data/bin/xray_trace_memcached.d

@@ -0,0 +1,20 @@
+#!/usr/sbin/dtrace -s
+#pragma D option quiet
+#pragma D option dynvarsize=64m
+
+
+pid*:memcached:*do_item_update*:entry { 
+    printf("COMMAND == %s \n", probefunc);
+}
+
+pid*:memcached:process_get_command:entry { 
+    self->conn_id = arg0;
+/*    self->pointer_to_string = copyin(arg1, 4); */
+    printf("GET == connection %d == update %p %d\n", arg0, arg1, arg2);
+}
+
+pid*:memcached:process_update_command:entry { 
+    self->conn_id = arg0;
+/*    self->pointer_to_string = copyin(arg1, 4); */
+    printf("UPDATE == connection %d == update %p %d\n", arg0, arg1, arg2);
+}

data/bin/xray_trace_mysql.d

@@ -0,0 +1,30 @@
+#!/usr/sbin/dtrace -s
+#pragma D option quiet
+#pragma D option dynvarsize=64m
+
+
+/*
+ * Inspired by Joyent's http://www.joyeur.com/2007/10/03/using-dtrace-on-mysql
+ */
+ 
+/*
+ * MySQL query parsing (captures all incoming queries)
+ */
+ 
+ /* TODO For example we can see what queries are executed the most: => Top 10 queries */
+pid*::*mysql*:entry
+{
+    printf("%Y %s\n", walltimestamp, copyinstr(arg1));
+}
+
+
+/*
+ * Now lets say we want to find out how long a query took to execute. 
+ * The function mysql_execute_command does the actual execution of 
+ * the queries so all we do here is subtract the entry and return 
+ * timestamps of this function.
+ */
+pid*:mysqld:*mysql_execute_command*:entry
+{
+    printf("OK");
+}

data/bin/xray_trace_rails_response_times.d

@@ -0,0 +1,114 @@
+#!/usr/sbin/dtrace -s
+#pragma D option quiet
+#pragma D option aggsortrev
+#pragma D option dynvarsize=64m
+
+/*
+ * Trace Rails controller actions and database response times.
+ * 
+ * Report average response time, total elapsed time and invocation count
+ * for all controller actions and datase queries.
+ *
+ * Also print response time distribution diagrams for global and individual
+ * action / query.
+ *
+ * Usage:
+ *
+ *     sudo /usr/bin/xray_trace_rails_response_times.d -p <a pid>
+ *
+ *     sudo /usr/bin/xray_trace_rails_response_times.d -c "ruby -v"
+ *
+ *     sudo dtrace -s /usr/bin/xray_trace_rails_response_times.d -p <a pid>
+ */ 
+this string name;
+this string action;
+this string query;
+
+dtrace:::BEGIN 
+{
+    printf("Tracing... Hit Ctrl-C to end.\n");
+    depth = 0;
+}
+
+ruby$target::ruby_dtrace_probe:
+/(this->name = copyinstr(arg0)) == "request-start"/ 
+{
+    self->request_start[copyinstr(arg1)] = timestamp;
+}
+
+
+ruby$target::ruby_dtrace_probe:
+/(this->name = copyinstr(arg0)) == "request-end" && self->request_start[(this->action = copyinstr(arg1))]/ 
+{	
+    this->elapsed = timestamp - self->request_start[this->action];
+    @re_count[this->action] = count();
+    @re_eavg[this->action] = avg(this->elapsed);
+    @re_esum[this->action] = sum(this->elapsed);
+    @re_edist[this->action] = quantize(this->elapsed);
+    @re_all_edist["All Requests"] = quantize(this->elapsed);
+    self->request_start[this->action] = 0;
+}
+
+ruby$target::ruby_dtrace_probe:
+/(this->name = copyinstr(arg0)) == "db-start"/
+{
+    self->db_start[copyinstr(arg1)] = timestamp;
+}
+
+
+ruby$target::ruby_dtrace_probe:
+/(this->name = copyinstr(arg0)) == "db-end" && self->db_start[(this->query = copyinstr(arg1))]/ 
+{	
+    @db_count[this->query] = count();
+    this->elapsed = timestamp - self->db_start[this->query];
+    @db_eavg[this->query] = avg(this->elapsed);
+    @db_esum[this->query] = sum(this->elapsed);
+    @db_edist[this->query] = quantize(this->elapsed);
+    @db_all_edist["All Queries"] = quantize(this->elapsed);
+    self->db_start[this->query] = 0;
+}
+
+dtrace:::END
+{
+    normalize(@re_eavg, 1000);
+    normalize(@re_esum, 1000); 
+    normalize(@db_eavg, 1000);
+    normalize(@db_esum, 1000);
+
+    printf("\n================================================\n");
+    printf("        Controller Response Times\n");
+    printf("================================================\n\n");
+
+    setopt("aggsortpos", "0");   /* Sort on avg time */
+    printf("%-50s %s\n", " _________ Action _________", "_ Avg. (us) _  Total (us) _ Count _\n");
+    printa("%-50.50s %@12d %@12d %@6d\n", @re_eavg, @re_esum, @re_count);
+    
+
+    printf("\n================================================\n");
+    printf("        Database Response Times\n");
+    printf("================================================\n");
+
+    setopt("aggsortpos", "0");   /* Sort on avg time */
+    printf("%-100s %s\n", " _________ Query _________", "_ Avg. (us) _  Total (us) _ Count _\n");
+    printa("%-100.100s %@12d %@12d %@6d\n", @db_eavg, @db_esum, @db_count);
+
+    printf("\n================================================\n");
+    printf("        Response Time Summary\n");
+    printf("================================================\n\n");
+    
+    printa(@re_all_edist);
+    printa(@db_all_edist);
+
+    printf("\n================================================\n");
+    printf("        Controller Response Time Distribution\n");
+    printf("================================================\n\n");
+    
+    printa(@re_edist);
+
+    printf("\n================================================\n");
+    printf("        DB Response Time Distribution\n");
+    printf("================================================\n\n");
+    
+    printa(@db_edist);    
+}
+

data/lib/xray.rb

@@ -0,0 +1,2 @@
+require File.dirname(__FILE__) + '/xray/thread_dump_signal_handler'
+require File.dirname(__FILE__) + '/xray/dtrace/tracer'

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, extra_options = {}, &block) 
+    firing('render', options.to_s) do
+       render_without_tracing options, extra_options
+    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