ruby-dtrace 0.0.5 → 0.0.6

data/History.txt

@@ -1,4 +1,9 @@
-== 0.0.4 / 2008-01-24
+== 0.0.6 / 2008-02-17
+
+ * Add Dtrace::Provider, which allows creation of USDT providers from
+   Ruby, without the need to patch the interpreter.
+
+== 0.0.5 / 2008-01-24
 
  * Add DtraceErrData and DtraceDropData for access to error 
    and drop information

data/Manifest.txt

@@ -19,6 +19,11 @@ ext/dtrace_recdesc.c
 ext/dtrace_util.c
 ext/extconf.rb
 lib/dtrace.rb
+lib/dtrace/probe.rb
+lib/dtrace/provider.rb
+lib/dtrace/provider/osx.rb
+lib/dtrace/provider/solaris.rb
+lib/dtrace/tracer.rb
 lib/dtraceaggregate.rb
 lib/dtraceaggregateset.rb
 lib/dtraceconsumer.rb
@@ -50,3 +55,4 @@ test/test_dtrace_profile.rb
 test/test_dtrace_repeat.rb
 test/test_dtrace_rubyprobe.rb
 test/test_dtrace_typefilter.rb
+test/test_dynusdt.rb

data/ext/dtrace_util.c

@@ -3,6 +3,7 @@
  */
 
 #include "dtrace_api.h"
+#include <ctype.h>
 
 RUBY_EXTERN VALUE eDtraceException;
 

data/lib/dtrace.rb

@@ -63,7 +63,7 @@ require 'dtracedata'
 #   end
 
 class Dtrace
-  VERSION = '0.0.5'
+  VERSION = '0.0.6'
 
   STATUS_NONE    = 0
   STATUS_OKAY    = 1

data/lib/dtrace/probe.rb

@@ -0,0 +1,49 @@
+#
+# Ruby-Dtrace
+# (c) 2007 Chris Andrews <chris@nodnol.org>
+#
+
+class Dtrace
+  # DTrace::Probe - Using dynamically created USDT probes in Ruby
+  # programs:
+  #
+  # Having created the following probes with Dtrace::Provider:
+  #
+  #   74777 action_controller12297 action_controller.so process_finish process-finish
+  #   74778 action_controller12297 action_controller.so process_start process-start
+  # 
+  # you can fire them with the following Ruby statements:
+  #
+  #   Dtrace::Probe::ActionController.process_start do |p|
+  #     p.fire(request.url)
+  #   end
+  #
+  # Note that the generated class corresponding to the provider is
+  # simply the provider class, camelized. 
+  #
+  # The generated method corresponding to the probe name (with -
+  # replaced by _) yields a probe object, on which you can call fire(),
+  # passing arguments of the appropriate types -- you are responsible
+  # for any type conversions necessary. 
+  #
+  # fire() takes as many arguments as you defined for the probe: if
+  # you have generated a list of arguments to pass to fire(), use the
+  # splat operator to expand the list:
+  # 
+  #   Dtrace::Probe::MyProvider.my_probe do |p|
+  #     args_list = [ some operation to get a list ]
+  #     p.fire(*args_list)
+  #   end
+  # 
+  # This yield/fire() syntax exposes the is-enabled feature of the
+  # generated USDT probes: if the probe is not enabled, then the yield
+  # does not happen: this allows you to put relatively expensive work
+  # in the block, and know it is only called if the probe is enabled.
+  # This way, the probe-disabled overhead of these providers is
+  # reduced to a single method call, to a C-implemented method which
+  # simply wraps the DTrace IS_ENABLED() macro for the probe.
+  #
+  class Probe
+  end
+end
+

data/lib/dtrace/provider.rb

@@ -0,0 +1,236 @@
+#
+# Ruby-Dtrace
+# (c) 2007 Chris Andrews <chris@nodnol.org>
+#
+
+require 'dtrace/probe'
+require 'dtrace/provider/solaris'
+require 'dtrace/provider/osx'
+require 'pathname'
+require 'tempfile'
+
+DTRACE = '/usr/sbin/dtrace'
+
+class Dtrace
+
+  # A DTrace provider. Allows creation of USDT probes on a running
+  # Ruby program, by dynamically creating an extension module
+  # implementing the probes, and compiling and loading it. You can use
+  # this with a Ruby interpreter compiled with the core DTrace probes,
+  # but you don't have to.
+  #
+  # This requires the DTrace and Ruby toolchains to be available:
+  # dtrace(1M), and the compiler and linker used to build Ruby. The
+  # process is similar to RubyInline, but the actual RubyInline
+  # library is not required (the build process for DTrace USDT probes
+  # is sufficiently differnent to a standard Ruby extension that it's
+  # not worth using it).
+  #
+  # Both Solaris and OSX 10.5 are supported. Other DTrace-supporting
+  # platforms can be added by creating a new class under
+  # Dtrace::Provider and implementing or overriding the required steps
+  # in the build process.
+  #
+  # Firing probes is explained in Dtrace::Probe.
+  #
+  # There are some limitations:
+  #
+  # You cannot choose all the components of the probe name: you can
+  # choose the provider and probe name, but the module and function
+  # components will be derived by DTrace, and won't be meaningful
+  # (they'll refer to the shim extension that gets created, not to
+  # anything in your Ruby program). It seems unlikely it's possible to
+  # change this. 
+  #
+  # You cannot currently set D attributes: they're hardcoded to a
+  # default set. This will change. 
+  #
+  # The extension will currently be rebuilt every time the provider is
+  # created, as there's not yet any support for packaging the provider
+  # in some way. This will change, to something along the lines of
+  # what RubyInline does to allow a pre-built extension to be used.
+  #
+  class Provider
+
+    class BuildError < StandardError; end
+
+    # Creates a DTrace provider. Causes a shim extension to be built
+    # and loaded, implementing the probes. 
+    #
+    # 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. 
+    # 
+    def self.create(name)
+      if RUBY_PLATFORM =~ /darwin/
+        provider = Dtrace::Provider::OSX.new(name)
+      else
+        provider = Dtrace::Provider::Solaris.new(name)
+      end
+      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)
+    #
+    # The probe will be named based on the provider name and the
+    # probe's name:
+    #
+    #   provider_name:provider_name.so:probe_name:probe-name
+    #
+    # See the limitations explained elsewhere for an explanation of
+    # this redundancy in probe names.
+    #
+    def probe(name, *types) 
+      typemap = { :string => 'char *', :integer => 'int' } 
+      @probes[name] = types.map {|t| typemap[t]} 
+    end
+
+    def initialize(name)
+      @name   = name.to_s
+      @class  = camelize(name)
+      @probes = {}
+    end
+
+    def enable
+      Tempfile.open("dtrace_probe_#{@name}") do |f|
+        p = Pathname.new(f.path)
+        @tempdir = "#{p.dirname}/#{@name}" 
+        begin
+          Dir.mkdir @tempdir
+        rescue Errno::EEXIST
+          nil
+        end
+
+        # Probe setup is split up for easy overriding
+        definition
+        header
+        source
+        ruby_object
+        dtrace_object
+        link
+        load
+      end
+    end
+
+    protected
+
+    def run(cmd)
+      result = `#{cmd}`
+      if $? != 0
+        raise BuildError.new("Error running:\n#{cmd}\n\n#{result}")
+      end
+    end
+
+    def hdrdir
+      %w(srcdir archdir).map { |name|
+        dir = Config::CONFIG[name]
+      }.find { |dir|
+        dir and File.exist? File.join(dir, "/ruby.h")
+      } or abort "ERROR: Can't find header dir for ruby. Exiting..."
+    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
+
+    # compose provider definition .d file
+    def definition
+      stability = <<EOS
+#pragma D attributes Evolving/Evolving/Common provider #{@name} provider
+#pragma D attributes Private/Private/Common provider #{@name} module
+#pragma D attributes Private/Private/Common provider #{@name} function
+#pragma D attributes Evolving/Evolving/Common provider #{@name} name
+#pragma D attributes Evolving/Evolving/Common provider #{@name} args
+EOS
+      File.open("#{@tempdir}/probes.d", 'w') do |io|
+        io << "provider #{@name} {\n"
+        @probes.each_pair do |name, types|
+          probename = name.to_s.gsub(/_/, '__')
+          typesdesc = types.join(', ')
+          probedesc = "  probe #{probename}(#{typesdesc});\n"
+          io << probedesc
+        end
+        io << "\n};\n\n#{stability}"
+      end
+    end
+
+    def header
+      run "#{DTRACE} -h -s #{@tempdir}/probes.d -o #{@tempdir}/probes.h"
+    end
+
+    # Generate the C source for the provider class
+    def source
+      rb2c = { 'char *' => 'STR2CSTR', 'int' => 'FIX2INT' }
+      
+      File.open("#{@tempdir}/probes.c", 'w') do |io|
+        io.puts '#include "ruby.h"'
+        io.puts "#include \"#{@tempdir}/probes.h\""
+
+        @probes.each_pair do |name, types|
+          defn_args = []
+          call_args = []
+          types.each_with_index { |type, i| defn_args << "#{type} arg#{i}" }
+          types.each_with_index { |type, i| call_args << "#{rb2c[type]}(rb_ary_entry(args, #{i}))" }
+          
+          io.puts <<EOC
+static VALUE #{name}(VALUE self) {
+  if (#{@name.upcase}_#{name.to_s.upcase}_ENABLED()) {
+    VALUE args = rb_yield(self);
+    #{@name.upcase}_#{name.to_s.upcase}(#{call_args.join(', ')});
+  }
+  return Qnil;
+}
+EOC
+        end
+        io.puts <<EOC
+static VALUE fire(VALUE self, VALUE args) {
+  return args;
+}
+
+void Init_#{@name}() {
+  VALUE c = rb_cObject;
+  rb_define_method(c, "fire", (VALUE(*)(ANYARGS))fire, -2);
+EOC
+        
+        @probes.each_pair do |name, types|
+          io.puts "  rb_define_singleton_method(c, \"#{name}\", (VALUE(*)(ANYARGS))#{name}, 0);"
+        end
+        
+        io.puts '}'
+      end
+    end
+    
+    def load
+      # Load the generated extension with a full path (saves adjusting
+      # $:) Done in the context of an anonymous class, since the
+      # module does not itself define a class.  TODO: find a way of
+      # doing this without string eval...
+      lib = "#{@tempdir}/#{@name}"
+      c = Class.new
+      c.module_eval do 
+        require lib
+      end
+      eval "Dtrace::Probe::#{@class} = c"
+    end
+    
+  end
+end

data/lib/dtrace/provider/osx.rb

@@ -0,0 +1,25 @@
+#
+# Ruby-Dtrace
+# (c) 2007 Chris Andrews <chris@nodnol.org>
+#
+
+class Dtrace
+  class Provider
+    class OSX < Provider
+      
+      # build the .bundle
+      def ruby_object
+        run "#{Config::CONFIG['LDSHARED']} -I #{hdrdir} -o #{@tempdir}/#{@name}.bundle #{@tempdir}/probes.c"
+      end
+
+      def dtrace_object
+        # no-op on OSX
+      end
+
+      def link
+        # no-op on OSX
+      end
+      
+    end
+  end
+end

data/lib/dtrace/provider/solaris.rb

@@ -0,0 +1,29 @@
+#
+# Ruby-Dtrace
+# (c) 2007 Chris Andrews <chris@nodnol.org>
+#
+
+require 'rbconfig'
+
+class Dtrace
+  class Provider
+    class Solaris < Provider
+
+      # build the .o 
+      def ruby_object
+        run "#{Config::CONFIG['CC']} -I#{hdrdir} -o #{@tempdir}/#{@name}.o -c #{@tempdir}/probes.c"
+      end
+
+      # build the dtrace.o (dtrace -G)
+      def dtrace_object
+        run "/usr/sbin/dtrace -G -s #{@tempdir}/probes.d -o #{@tempdir}/probes.o #{@tempdir}/#{@name}.o"
+      end
+
+      # build the .so
+      def link
+        run "#{Config::CONFIG['CC']} -shared -o #{@tempdir}/#{@name}.so #{@tempdir}/#{@name}.o #{@tempdir}/probes.o"
+      end
+
+    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/plugin/dtrace/lib/dtrace_report.rb

@@ -5,6 +5,7 @@ module DtraceReport
 
   def self.included(base)
     base.extend DtraceMacro
+    @@tracer = nil
   end
 
   module DtraceMacro
@@ -43,19 +44,23 @@ module DtraceReport
   end
 
   def enable_dtrace
-    @@tracer.start_dtrace($$)
+    if @@tracer
+      @@tracer.start_dtrace($$)
+    end
   end
 
   def append_dtrace_report
-    @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
+    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
   

data/test/test_dynusdt.rb

@@ -0,0 +1,135 @@
+#
+# Ruby-Dtrace
+# (c) 2007 Chris Andrews <chris@nodnol.org>
+#
+
+require 'dtrace'
+require 'dtrace/provider'
+require 'test/unit'
+require 'rbconfig'
+
+# Tests for the Dtrace "dynamic USDT" library
+
+class TestDynUsdt < Test::Unit::TestCase
+
+  def test_create_usdt
+    Dtrace::Provider.create :test_provider_create_usdt do |p|
+      p.probe :test_probe, :string
+    end
+
+    t = Dtrace.new
+    t.setopt("bufsize", "4m")
+
+    progtext = 'test_provider_create_usdt*:::test-probe { trace(copyinstr(arg0)); }'
+
+    prog = t.compile progtext
+    prog.execute
+    t.go
+    
+    c = DtraceConsumer.new(t)
+    
+    Dtrace::Probe::TestProviderCreateUsdt.test_probe do |p|
+      p.fire "test_argument"
+    end
+
+    i = 0
+    c.consume_once do |d|
+      i = i + 1
+      assert d
+      assert_not_nil d.probe
+      assert_equal "test_provider_create_usdt#{$$.to_s}:test_provider_create_usdt.#{Config::CONFIG['DLEXT']}:test_probe:test-probe", d.probe.to_s
+      assert_equal 1, d.data.length
+      assert_equal "test_argument", d.data[0].value
+    end
+    assert_equal 1, i
+  end
+
+  def test_create_usdt_argtypes
+    Dtrace::Provider.create :test_provider_create_usdt_argtypes do |p|
+      p.probe :test_probe_string, :string
+      p.probe :test_probe_int,    :integer
+    end
+
+    t = Dtrace.new
+    t.setopt("bufsize", "4m")
+
+    progtext = <<EOD
+test_provider_create_usdt_argtypes*:::test-probe-string { trace(copyinstr(arg0)); }
+test_provider_create_usdt_argtypes*:::test-probe-int    { trace(arg0);            }
+EOD
+
+    prog = t.compile progtext
+    prog.execute
+    t.go
+    
+    c = DtraceConsumer.new(t)
+    
+    Dtrace::Probe::TestProviderCreateUsdtArgtypes.test_probe_string do |p|
+      p.fire "test_argument"
+    end
+
+    Dtrace::Probe::TestProviderCreateUsdtArgtypes.test_probe_int do |p|
+      p.fire 42
+    end
+
+    i = 0
+    c.consume_once do |d|
+      assert d
+      assert_not_nil d.probe
+      if d.probe.name == 'test-probe-string'
+        assert_equal "test_argument", d.data[0].value
+        i = i + 1
+      elsif d.probe.name == 'test-probe-int'
+        assert_equal 42, d.data[0].value
+        i = i + 1
+      end
+    end
+    assert_equal 2, i
+  end
+
+  def test_create_usdt_manyargs
+    Dtrace::Provider.create :test_provider_create_usdt_manyargs do |p|
+      p.probe :test_probe, :string, :string, :string, :string, :string, :string, :string, :string
+    end
+
+    t = Dtrace.new
+    t.setopt("bufsize", "4m")
+
+    progtext = <<EOD
+test_provider_create_usdt_manyargs*:::test-probe 
+{ 
+  trace(copyinstr(arg0));
+  trace(copyinstr(arg1));
+  trace(copyinstr(arg2));
+  trace(copyinstr(arg3));
+  trace(copyinstr(arg4));
+  trace(copyinstr(arg5));
+  trace(copyinstr(arg6));
+  trace(copyinstr(arg7));
+}
+EOD
+
+    prog = t.compile progtext
+    prog.execute
+    t.go
+    
+    c = DtraceConsumer.new(t)
+    
+    Dtrace::Probe::TestProviderCreateUsdtManyargs.test_probe do |p|
+      values_list = (0..7).map {|i| "value #{i.to_s}" }
+      p.fire(*values_list)
+    end
+
+    i = 0
+    c.consume_once do |d|
+      i = i + 1
+      assert_equal 8, d.data.length
+      (0..7).each do |j|
+        assert_equal "value #{j.to_s}", d.data[j].value
+      end
+    end
+    assert_equal 1, i
+  end
+
+end
+    

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.4
 specification_version: 1
 name: ruby-dtrace
 version: !ruby/object:Gem::Version 
-  version: 0.0.5
-date: 2008-01-24 00:00:00 +00:00
+  version: 0.0.6
+date: 2008-02-17 00:00:00 +00:00
 summary: Ruby bindings for libdtrace
 require_paths: 
 - lib
@@ -51,6 +51,11 @@ files:
 - ext/dtrace_util.c
 - ext/extconf.rb
 - lib/dtrace.rb
+- lib/dtrace/probe.rb
+- lib/dtrace/provider.rb
+- lib/dtrace/provider/osx.rb
+- lib/dtrace/provider/solaris.rb
+- lib/dtrace/tracer.rb
 - lib/dtraceaggregate.rb
 - lib/dtraceaggregateset.rb
 - lib/dtraceconsumer.rb
@@ -82,6 +87,7 @@ files:
 - test/test_dtrace_repeat.rb
 - test/test_dtrace_rubyprobe.rb
 - test/test_dtrace_typefilter.rb
+- test/test_dynusdt.rb
 test_files: 
 - test/test_dtrace.rb
 - test/test_dtrace_aggregates.rb
@@ -91,6 +97,7 @@ test_files:
 - test/test_dtrace_repeat.rb
 - test/test_dtrace_rubyprobe.rb
 - test/test_dtrace_typefilter.rb
+- test/test_dynusdt.rb
 rdoc_options: 
 - --main
 - README.txt