chrisa-ruby-dtrace 0.2.0

data/lib/dtrace/provider.rb

@@ -0,0 +1,231 @@
+#
+# Ruby-Dtrace
+# (c) 2008 Chris Andrews <chris@nodnol.org>
+#
+
+require 'dtrace'
+require 'dtrace/dof'
+require 'dtrace/probe'
+require 'dtrace/provider/probedef'
+
+class Dtrace
+
+  # A DTrace provider. Allows creation of USDT probes on a running
+  # Ruby program. You can use this with a Ruby interpreter compiled
+  # with the core DTrace probes, but you don't have to.
+  #
+  # Firing probes is explained in Dtrace::Probe.
+  #
+  class Provider
+    include Dtrace::Dof::Constants
+
+    Typemap = { :string => 'char *', :integer => 'int' } 
+
+    # Creates a DTrace provider.
+    #
+    # Example:
+    # 
+    #   Dtrace::Provider.create :action_controller do |p|
+    #     p.probe :process_start,  :string
+    #     p.probe :process_finish, :string, :integer
+    #   end
+    #
+    # The symbol passed to create becomes the name of the provider,
+    # and the class exposed under Dtrace::Probe in Ruby (camelized, so
+    # the above statement creates Dtrace::Probe::ActionController).
+    # 
+    # create yields a Provider for the current platform, on which you
+    # can call probe, to create the individual probes. 
+    # 
+    # You can override the module name in the created probes, by
+    # passing in an hash:
+    #
+    #   Dtrace::Provider.create :foo, { :module => 'somemodule' } do |p|
+    #     p.probe...
+    #   end
+    def self.create(name, options={})
+      options[:module] ||= 'ruby'
+      provider = Dtrace::Provider.new(name, options[:module])
+      yield provider
+      provider.enable
+    end
+
+    # Creates a DTrace USDT probe. Arguments are the probe name, and
+    # then the argument types it will accept. The following argument
+    # types are supported:
+    #
+    # :string  (char *)
+    # :integer (int)
+    #
+    # Providing an options hash as the second argument allows you to
+    # override the function name, otherwise it will be taken from the
+    # caller of this function:
+    #
+    #   p.probe :foo, { :function => 'somefunction' }, :int, ...
+    #
+    def probe(name, *types) 
+      options = {}
+      if types[0].respond_to? :keys
+        options = types.shift
+      end
+      options[:function] ||= Kernel.caller[0].match(/`(.*)'/)[1]
+
+      pd = Dtrace::Provider::ProbeDef.new(name, options[:function])
+      types.each do |t|
+        if Typemap[t].nil?
+          raise Dtrace::Exception.new("type '#{t}' invalid")
+        else
+          pd.args << Typemap[t]
+        end
+      end
+
+      @probe_defs << pd
+    end
+
+    def initialize(provider_name, module_name)
+      @name       = provider_name.to_s
+      @module     = module_name.to_s
+      @class      = camelize(provider_name)
+      @probe_defs = []
+    end
+
+    def enable
+      f = Dtrace::Dof::File.new
+      
+      strtab = Dtrace::Dof::Section::Strtab.new(0)
+      f.sections << strtab
+
+      s = Dtrace::Dof::Section.new(DOF_SECT_PROBES, 1)
+      probes = Array.new
+      stubs = Hash.new
+      argidx = 0
+      offidx = 0
+      @probe_defs.each do |pd|
+        argc = pd.argc
+        
+        argv = 0
+        pd.args.each do |type|
+          i = strtab.add(type)
+          argv = i if argv == 0
+        end
+        
+        probe = Dtrace::Probe.new(argc)
+        probes <<
+          {
+          :name     => strtab.add(pd.name),
+          :func     => strtab.add(pd.function),
+          :noffs    => 1,
+          :enoffidx => offidx,
+          :argidx   => argidx,
+          :nenoffs  => 1,
+          :offidx   => offidx,
+          :addr     => probe.addr,
+          :nargc    => argc,
+          :xargc    => argc,
+          :nargv    => argv,
+          :xargv    => argv,
+        }
+        
+        stubs[pd.name] = probe
+        argidx += argc
+        offidx += 1
+      end
+      s.data = probes
+      f.sections << s
+
+      s = Dtrace::Dof::Section.new(DOF_SECT_PRARGS, 2)
+      s.data = Array.new
+      @probe_defs.each do |pd|
+        pd.args.each_with_index do |arg, i|
+          s.data << i
+        end
+      end
+      if s.data.empty?
+        s.data = [ 0 ]
+      end
+      f.sections << s
+
+      s = Dtrace::Dof::Section.new(DOF_SECT_PROFFS, 3)
+      s.data = Array.new
+      @probe_defs.each do |pd|
+        s.data << stubs[pd.name].probe_offset(f.addr, pd.argc)
+      end
+      if s.data.empty?
+        s.data = [ 0 ]
+      end
+      f.sections << s
+
+      s = Dtrace::Dof::Section.new(DOF_SECT_PRENOFFS, 4)
+      s.data = Array.new
+      @probe_defs.each do |pd|
+        s.data << stubs[pd.name].is_enabled_offset(f.addr)
+      end
+      if s.data.empty?
+        s.data = [ 0 ]
+      end
+      f.sections << s
+      
+      s = Dtrace::Dof::Section.new(DOF_SECT_PROVIDER, 5)
+      s.data = {
+        :strtab => 0,
+        :probes => 1,
+        :prargs => 2,
+        :proffs => 3,
+        :prenoffs => 4,
+        :name => strtab.add(@name),
+        :provattr => { 
+          :name  => DTRACE_STABILITY_EVOLVING,
+          :data  => DTRACE_STABILITY_EVOLVING,
+          :class => DTRACE_STABILITY_EVOLVING 
+        },
+        :modattr  => { 
+          :name => DTRACE_STABILITY_PRIVATE,
+          :data => DTRACE_STABILITY_PRIVATE,
+          :class => DTRACE_STABILITY_EVOLVING 
+        },
+        :funcattr => { 
+          :name => DTRACE_STABILITY_PRIVATE,
+          :data => DTRACE_STABILITY_PRIVATE,
+          :class => DTRACE_STABILITY_EVOLVING
+        },
+        :nameattr => { 
+          :name => DTRACE_STABILITY_EVOLVING,
+          :data => DTRACE_STABILITY_EVOLVING,
+          :class => DTRACE_STABILITY_EVOLVING
+        },
+        :argsattr => {
+          :name => DTRACE_STABILITY_EVOLVING,
+          :data => DTRACE_STABILITY_EVOLVING,
+          :class => DTRACE_STABILITY_EVOLVING
+        },
+      }
+      f.sections << s
+      
+      f.generate
+      Dtrace::Dof.loaddof(f, @module)
+
+      c = Class.new
+      c.class_eval do
+        @@probes = stubs
+        def self.method_missing(name)
+          name = name.to_s
+          unless @@probes[name].nil?
+            if @@probes[name].is_enabled?
+              yield @@probes[name]
+            end
+          end
+        end
+      end
+      eval "Dtrace::Probe::#{@class} = c"
+
+    end
+
+    private
+
+    def camelize(lower_case_and_underscored_word)
+      # Pinched from ActiveSupport's Inflector
+      lower_case_and_underscored_word.to_s.gsub(/\/(.?)/) { "::" + $1.upcase }.gsub(/(^|_)(.)/) { $2.upcase }
+    end
+    
+  end
+end

data/lib/dtrace/record.rb

@@ -0,0 +1,11 @@
+#
+# Ruby-Dtrace
+# (c) 2007 Chris Andrews <chris@nodnol.org>
+#
+# A scalar DTrace record. Its value is as set by the DTrace action
+# which triggered it.
+class Dtrace
+  class Record
+    attr_accessor :value
+  end
+end

data/lib/dtrace/stackrecord.rb

@@ -0,0 +1,31 @@
+#
+# Ruby-Dtrace
+# (c) 2007 Chris Andrews <chris@nodnol.org>
+#
+
+# A record representing the result of a stack() or ustack()
+# action. Its value is a list of symbolic stack frames:
+# 
+#   #<DtraceStackRecord:0x14e24 @value=
+#           ["libSystem.B.dylib`__sysctl+0xa",
+#            "libdtrace.dylib`dt_aggregate_go+0x9a",
+#            "dtrace_api.bundle`dtrace_hdl_go+0x30",
+#            "libruby.1.dylib`rb_eval_string_wrap+0x40fd",
+#            "libruby.1.dylib`rb_eval_string_wrap+0x4cdb",
+#            ...
+#            "libruby.1.dylib`rb_apply+0x392",
+#            "libruby.1.dylib`rb_eval_string_wrap+0xe82"]>
+#
+class Dtrace
+  class StackRecord
+    attr_reader :value
+
+    # Given a stack as a string returned from DTrace, set the value of
+    # this record to a list of stack frames.
+    def parse(raw)
+      frames = raw.split(/\n/)
+      @value = frames.map {|f| f.lstrip }.select {|f| f.length > 0 }
+    end
+
+  end
+end

data/lib/dtrace/tracer.rb

@@ -0,0 +1,35 @@
+#
+# Ruby-Dtrace
+# (c) 2007 Chris Andrews <chris@nodnol.org>
+#
+
+# Leopard's ruby-probe is DTracer, Solaris's is Tracer.
+
+class Dtrace
+  class Tracer
+    
+    class NullTracer
+      def self.fire(arg0, arg1)
+        puts "NullTracer: #{arg0} #{arg1}"
+      end
+    end
+
+    @@tracer = nil
+    def self.fire(*args)
+      if @@tracer == nil
+        begin
+          # Avoid getting ourselves here:
+          @@tracer = Module.const_get('Tracer')
+        rescue NameError
+          begin
+            @@tracer = DTracer
+          rescue NameError
+            @@tracer = Dtrace::Tracer::NullTracer
+          end
+        end
+      end
+      @@tracer.fire(*args)
+    end
+          
+  end
+end

data/lib/dtrace.rb

@@ -0,0 +1,74 @@
+#
+# Ruby-Dtrace
+# (c) 2007 Chris Andrews <chris@nodnol.org>
+#
+
+require 'dtrace_api'
+require 'dtrace/record'
+require 'dtrace/consumer'
+require 'dtraceconsumer'
+require 'dtrace/aggregate'
+require 'dtrace/aggregateset'
+require 'dtrace/probedata'
+require 'dtrace/probedesc'
+require 'dtrace/stackrecord'
+require 'dtrace/printfrecord'
+require 'dtrace/data'
+require 'dtrace/version'
+
+# A DTrace handle. Provides methods for inspecting available probes,
+# compiling and running programs, and for setting up callbacks to
+# receive trace data.
+#
+# The general structure of a Dtrace-based program is:
+#
+# * Create a handle with Dtrace.new
+# * Set options
+# * Compile the program, possibly inspecting the return Dtrace::ProgramInfo
+# * Execute the program
+# * Start tracing
+# * Consume data, either directly by setting up callbacks, or using a Dtrace::Consumer.
+# * Stop tracing
+#
+# === Listing probes
+#
+#   d.each_probe do |p|
+#     puts "#{p.provider}:#{p.mod}:#{p.func}:#{p.name}"
+#   end
+#
+# === Setting options
+#
+#   d.setopt("bufsize", "8m")
+#   d.setopt("aggsize", "4m")
+#   d.setopt("stackframes", "5")
+#   d.setopt("strsize", "131072")
+#
+# === Compiling a program
+#
+#   d.compile "syscall:::entry { trace(execname); stack(); }"
+#   d.execute
+#
+# === Setting up callbacks
+#
+#   d.buf_consumer(prob {|buf| yield buf })
+#   d.work(proc {|probe| yield probe }, proc {|rec| yield rec })
+#
+# === Creating a process
+#
+#   p = t.createprocess([ '/usr/bin/true' ])
+#   t.go
+#   p.continue
+#
+#   c = Dtrace::Consumer.new(t)
+#   c.consume do |d|
+#     ..
+#   end
+
+class Dtrace
+  STATUS_NONE    = 0
+  STATUS_OKAY    = 1
+  STATUS_EXITED  = 2
+  STATUS_FILLED  = 3
+  STATUS_STOPPED = 4
+end
+

data/lib/dtraceconsumer.rb

@@ -0,0 +1,9 @@
+#
+# Ruby-Dtrace
+# (c) 2007 Chris Andrews <chris@nodnol.org>
+#
+
+require 'dtrace/consumer'
+
+# Interface preservation - see Dtrace::Consumer.
+class DtraceConsumer < Dtrace::Consumer; end

data/plugin/dtrace/README

@@ -0,0 +1,81 @@
+Dtrace
+======
+
+A simple plugin to run a DTrace script while your Rails app runs. 
+
+Installation:
+
+  script/plugin install http://ruby-dtrace.rubyforge.org/svn/trunk/plugin/dtrace
+
+Or copy the plugin/dtrace directory from the installed ruby-dtrace gem
+to your app's vendor/plugins directory. 
+
+Choose a mode of operation:
+
+The process running DTrace needs additional privileges: on Solaris,
+you can grant the dtrace_* privileges, and on both Leopard and Solaris
+you can run the process as root. 
+
+This plugin can run in two modes: you can run the whole app with
+DTrace privileges, or you can run a helper process with the
+privileges, and the app will use DRb to communicate with it.
+
+If you choose to run the app as root, you need to set the :tracer
+option to the dtrace macro to :self, and if you choose to run the
+helper as root, you need to set the :tracer option to :helper. 
+
+Configuring the plugin:
+
+Add the following line to either the specific controller you want
+traced, or to the ApplicationController, in which case it will be
+applied to every controller in your app:
+
+  dtrace :on, :tracer => :self
+
+  or 
+
+  dtrace :on, :tracer => :helper
+
+You can also set the name of the script to be run, from the
+vendor/plugins/dtrace/scripts/ directory with the :script option:
+
+  dtrace :on, :tracer => :self, :script => 'rails_mysql.d'
+
+There are two scripts in the distribution: 
+ * default.d
+    - a very simple script to log system calls, which doesn't require 
+      a DTrace-enabled ruby.
+
+ * rails_mysql.d
+    - a simplified version of the script shown here:
+      http://blogs.sun.com/bmc/entry/dtrace_on_rails, which relies on
+      DTrace-enabled ruby, and the use of MySQL with the
+      libmysqlclient-based adapter, not the pure-ruby adapter.
+
+Troubleshooting:
+
+If you don't get a DTrace report, check the log for messages like:
+
+   DTrace start setup: unable to open dtrace (not root?)
+
+(indicating a lack of privileges to start DTrace: check your setting
+of the :tracer option, and how you are starting the application and/or
+helper).
+
+   DTrace start compile: probe description pid14484::mysql_real_query:entry does not match any probes
+
+(indicating the function mysql_real_query isn't found: either you're
+not using MySQL, or you are using the pure ruby client).
+
+   DTrace start compile: probe description ruby15253:::function-entry does not match any probes
+
+(indicating you are not using a DTrace-enabled ruby binary)
+
+A DRb::DRbConnError reported by Rails, like this:
+
+   druby://localhost:2999 - #<Errno::ECONNREFUSED: Connection refused - connect(2)>
+
+indicates you've selected the :helper option, but the helper isn't
+running. Check that your app can connect to localhost:2999 for the DRb
+service the helper provides.
+

data/plugin/dtrace/Rakefile

@@ -0,0 +1,22 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the dtrace plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the dtrace plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Dtrace'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/plugin/dtrace/bin/dtracer.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'drb'
+require 'pathname'
+
+# allow running standalone or in a rails app
+script_dir = Pathname.new(File.dirname(__FILE__)).realpath
+rails_script = script_dir + '../vendor/plugins/dtrace/bin'
+plugin_script = script_dir + '../../../../vendor/plugins/dtrace/bin'
+if rails_script.directory?
+  rails_root = script_dir + '../'
+elsif plugin_script.directory?
+  rails_root = script_dir + '../../../..'
+end
+$LOAD_PATH << File.join(rails_root + 'vendor/plugins/dtrace/lib')
+
+require 'dtracer'
+
+here = "druby://localhost:2999"
+tracer = Dtracer.new
+DRb.start_service here, tracer
+puts "DTrace helper started"
+begin
+  DRb.thread.join
+rescue Interrupt
+  exit 0
+end
+

data/plugin/dtrace/init.rb

@@ -0,0 +1,7 @@
+require 'dtrace_report'
+ActionController::Base.class_eval do
+  include DtraceReport
+  before_filter :enable_dtrace if RAILS_ENV == 'development'
+  after_filter :append_dtrace_report if RAILS_ENV == 'development'
+end
+

data/plugin/dtrace/lib/dtrace_helper.rb

@@ -0,0 +1,2 @@
+module DtraceHelper
+end

data/plugin/dtrace/lib/dtrace_report.rb

@@ -0,0 +1,67 @@
+require 'dtracer'
+require 'dtracer_client'
+
+module DtraceReport
+
+  def self.included(base)
+    base.extend DtraceMacro
+    @@tracer = nil
+  end
+
+  module DtraceMacro
+    def dtrace(enable=:on, options={})
+      if enable == :on
+
+        # Set tracer type, in-process or helper-process
+        if options[:tracer] == :self
+          tracer = Dtracer.new
+        elsif options[:tracer] == :helper
+          tracer = DtracerClient.new
+        else
+          raise "tracer option is self or helper"
+        end
+
+        tracer.logger = logger
+
+        # Set script, or default
+        if options[:script]
+          tracer.script = options[:script]
+        else
+          tracer.script = 'default.d'
+        end
+
+        DtraceReport.tracer = tracer
+      end
+    end
+  end
+
+  attr_reader :dtrace_report
+  attr_reader :dtrace_script
+
+  protected
+  def self.tracer=(tracer)
+    @@tracer = tracer
+  end
+
+  def enable_dtrace
+    if @@tracer
+      @@tracer.start_dtrace($$)
+    end
+  end
+
+  def append_dtrace_report
+    if @@tracer 
+      @dtrace_script = @@tracer.script
+      @dtrace_report = @@tracer.end_dtrace
+      # yuck!
+      old_template_root = @template.base_path
+      begin
+        @template.view_paths =  File.expand_path(File.dirname(__FILE__) + '/../views')
+        response.body.gsub!(/<\/body/, @template.render(:partial => 'dtrace/report') + '</body')
+      ensure
+        @template.view_paths = old_template_root
+      end
+    end
+  end
+  
+end

data/plugin/dtrace/lib/dtracer.rb

@@ -0,0 +1,52 @@
+require 'dtrace'
+
+class Dtracer
+  attr_writer :logger, :dprogram
+  attr_reader :script
+
+  def script=(script)
+    @script = script
+    scriptdir = File.expand_path(File.dirname(__FILE__) + "/../scripts")
+    @dprogram = IO.read("#{scriptdir}/#{script}")
+  end
+
+  def start_dtrace(pid)
+    begin
+      @d = Dtrace.new
+      @d.setopt("aggsize", "4m")
+      @d.setopt("bufsize", "4m")
+    rescue DtraceException => e
+      @logger.warn("DTrace start setup: #{e.message}")
+      return
+    end
+
+    begin
+      prog = @d.compile(@dprogram, pid.to_s)
+      prog.execute
+      @d.go
+    rescue DtraceException => e
+      @logger.warn("DTrace start compile: #{e.message}")
+    end
+  end
+  
+  def end_dtrace
+    # Check presence of handle and correct status.
+    return [] unless @d && @d.status == Dtrace::STATUS_OKAY
+
+    dtrace_data = nil
+    begin
+      c = DtraceConsumer.new(@d)
+      c.consume_once do |d|
+        dtrace_data = d
+      end
+    rescue DtraceException => e
+      @logger.warn("DTrace end: #{e.message}")
+    end
+    
+    if dtrace_data
+      return dtrace_data.data
+    else
+      return []
+    end
+  end
+end

data/plugin/dtrace/lib/dtracer_client.rb

@@ -0,0 +1,26 @@
+require 'drb'
+
+class DtracerClient
+  attr_writer :logger
+  attr_reader :script
+
+  def initialize
+    DRb.start_service
+    @tracer = DRbObject.new(nil, 'druby://localhost:2999')  
+  end
+
+  def script=(script)
+    @script = script
+    scriptdir = File.expand_path(File.dirname(__FILE__) + "/../scripts")
+    @tracer.dprogram = IO.read("#{scriptdir}/#{script}")
+  end
+
+  def start_dtrace(pid)
+    @tracer.start_dtrace(pid)
+  end
+  
+  def end_dtrace
+    @tracer.end_dtrace
+  end
+
+end