chrisa-ruby-dtrace 0.2.0

data/ext/stubs.txt

@@ -0,0 +1,78 @@
+disassembly of C probe stub:
+
+/*      3. void probe8(arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7) { */
+/*         <Function: probe8> */
+/*         [ 3]  805133c:  pushl   %ebp */
+/*         [ 3]  805133d:  movl    %esp,%ebp */
+/*         [ 3]  805133f:  subl    $8,%esp */
+/*      4.         TEST_TEST_INT_INT_INT_INT_INT_INT_INT_INT_PROBE(arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7); */
+/*         [ 4]  8051342:  pushl   0x24(%ebp) */
+/*         [ 4]  8051345:  pushl   0x20(%ebp) */
+/*         [ 4]  8051348:  pushl   0x1c(%ebp) */
+/*         [ 4]  805134b:  pushl   0x18(%ebp) */
+/*         [ 4]  805134e:  pushl   0x14(%ebp) */
+/*         [ 4]  8051351:  pushl   0x10(%ebp) */
+/*         [ 4]  8051354:  pushl   0xc(%ebp) */
+/*         [ 4]  8051357:  pushl   8(%ebp) */
+/*         [ 4]  805135a:  nop      */
+/*         [ 4]  805135b:  nop      */
+/*         [ 4]  805135c:  nop      */
+/*         [ 4]  805135d:  nop      */
+/*         [ 4]  805135e:  nop      */
+/*         [ 4]  805135f:  addl    $0x20,%esp */
+/*      5. } */
+/*         [ 5]  8051362:  leave    */
+/*         [ 5]  8051363:  ret      */
+
+Corresponding binary:
+
+/* 1330                                       55 89 e5 83  .....^[. ....U... */
+/* 1340  ec 08 ff 75 24 ff 75 20  ff 75 1c ff 75 18 ff 75  ...u$.u  .u..u..u */
+/* 1350  14 ff 75 10 ff 75 0c ff  75 08 90 90 90 90 90 83  ..u..u.. u....... */
+/* 1360  c4 20 c9 c3 */
+
+Hand-built 8-arg stub:
+
+/*   char insns[FUNC_SIZE] =  */
+/*     { */
+/*       0x55, 0x89, 0xe5, 0x83, 0xec, 0x08, */
+/*       0xff, 0x75, 0x24, */
+/*       0xff, 0x75, 0x20, */
+/*       0xff, 0x75, 0x1c, */
+/*       0xff, 0x75, 0x18, */
+/*       0xff, 0x75, 0x14, */
+/*       0xff, 0x75, 0x10, */
+/*       0xff, 0x75, 0x0c, */
+/*       0xff, 0x75, 0x08, */
+/*       0x90, 0x90, 0x90, 0x90, 0x90, */
+/*       0x83, 0xc4, 0x20, */
+/*       0xc9, 0xc3 */
+/*     }; */
+
+disassembly of is_enabled function:
+
+    21. int is_enabled(void) {
+        <Function: is_enabled>
+        [21]  805142a:  pushl   %ebp
+        [21]  805142b:  movl    %esp,%ebp
+        [21]  805142d:  subl    $8,%esp
+    22.         return TEST_TEST_PROBE_ENABLED() ? 1 : 0;
+        [22]  8051430:  xorl    %eax,%eax
+        [22]  8051432:  nop     
+        [22]  8051433:  nop     
+        [22]  8051434:  nop     
+        [22]  8051435:  movl    %eax,-4(%ebp)
+        [22]  8051438:  cmpl    $0,-4(%ebp)
+        [22]  805143c:  setne   %al
+        [22]  805143f:  movzbl  %al,%eax
+        [22]  8051442:  movl    %eax,-4(%ebp)
+        [22]  8051445:  movl    -4(%ebp),%eax
+    23. }
+        [23]  8051448:  leave   
+        [23]  8051449:  ret     
+
+Binary:
+
+                                     55 89 e5 83 ec 08  .......  ..U.....
+1430  33 c0 90 90 90 89 45 fc  83 7d fc 00 0f 95 c0 0f  3.....E. .}......
+1440  b6 c0 89 45 fc 8b 45 fc  c9 c3

data/lib/dtrace/aggregate.rb

@@ -0,0 +1,40 @@
+#
+# Ruby-Dtrace
+# (c) 2007 Chris Andrews <chris@nodnol.org>
+#
+
+# Represents an aggregation record built from a series of
+# DtraceAggData records.
+#
+# Intended to to built up by calling +add_record+ repeatedly with
+# Dtrace::AggData objects until a completed Dtrace::Aggregate is
+# returned.  (until a complete record is available, +add_record+
+# returns nil).
+#
+# See consumer.rb for an example of this.
+class Dtrace
+  class Aggregate
+    attr_reader :value, :tuple
+
+    # Create an empty Dtrace::Aggregate: use +add_record+ to add data.
+    def initialize
+      @tuple = Array.new
+    end
+    
+    # Add a Dtrace::AggData record to this aggregate. Returns nil until it
+    # receives a record of aggtype "last", when it returns the complete
+    # Dtrace::Aggregate.
+    def add_record(r)
+      case r.aggtype
+      when "tuple"
+        @tuple << r.value
+      when "value"
+        @value = r.value
+      when "last"
+        return self
+      end
+      nil
+    end
+
+  end
+end

data/lib/dtrace/aggregateset.rb

@@ -0,0 +1,19 @@
+#
+# Ruby-Dtrace
+# (c) 2007 Chris Andrews <chris@nodnol.org>
+#
+
+class Dtrace
+  class AggregateSet
+    attr_reader :data
+
+    def initialize
+      @data = Array.new
+    end
+    
+    def add_aggregate(agg)
+      @data << agg
+    end
+    
+  end
+end

data/lib/dtrace/consumer.rb

@@ -0,0 +1,174 @@
+#
+# Ruby-Dtrace
+# (c) 2007 Chris Andrews <chris@nodnol.org>
+#
+
+# A Dtrace::Consumer provides access to the data produced by the running
+# D program. Having compiled and executed a D program, you typically
+# create a Dtrace::Consumer, and wait for data. 
+#
+# You can either wait indefinitely for data, or consume all the data
+# waiting and then stop: if your D program consists of only of
+# aggregations, returned by printa() actions in the END block, this
+# will be the best approach. If you have a mix of trace() and printf()
+# actions elsewhere, you'll probably want to wait until interrupted,
+# the D program itself exits, or your program decides it has collected
+# enough data.
+#
+# The two approaches are implemented by the +consume+ and
+# +consume_once+ methods.
+#
+# The +consume+ and +consume_once+ methods accept a block to which is
+# yielded complete Dtrace::Data objects, one for each probe which fires.
+#
+# You must have already started tracing when you call +consume+ or
+# +consume_once+, so the general structure will look like:
+#
+#   t = Dtrace.new
+#   progtext = "..."
+#   prog = t.compile progtext
+#   prog.execute
+#   t.go 
+#   c = Dtrace::Consumer.new(t)
+#   c.consume_once do |d|
+#     # handle Dtrace::Data objects
+#     # ...
+#     # get bored:
+#     c.finish
+#   end
+
+class Dtrace
+  class Consumer
+
+    def initialize(t)
+      @t = t
+      @done = false
+      @types = []
+
+      @drophandler = nil
+      @errhandler = nil
+    end
+
+    private
+
+    # The consumer callbacks:
+    #
+    # DtraceRecDesc   -> rec_consumer
+    # DtraceProbeData -> probe_consumer
+    # DtraceBufData   -> buf_consumer
+    #
+    # We expect a sequence of calls to these procs, and we accumulate
+    # data in the @curr Dtrace::Data based on this:
+    #
+    # Dtrace::ProbeData (initial callback for a probe firing)
+    # Dtrace::RecDesc 
+    # ...
+    # Dtrace::RecDesc = nil (end of data)
+    #
+    
+    def rec_consumer(block)
+      proc do |rec|
+        if rec
+          @curr.add_recdata(rec)
+        else
+          @curr.finish
+          block.call(@curr)
+          @curr = Dtrace::Data.new(@types)
+        end
+      end
+    end
+    
+    def probe_consumer
+      proc do |probe|
+        @curr.add_probedata(probe)
+      end
+    end
+
+    def buf_consumer
+      proc do |buf|
+        @curr.add_bufdata(buf)
+      end
+    end
+
+    def filter_types(types)
+      @types = types
+      @curr = Dtrace::Data.new(types)
+    end
+    
+    public
+
+    # Provide a proc which will be executed when a drop record is
+    # received.
+    def drophandler(&block)
+      @drophandler = block
+      @t.drop_consumer(proc do |drop|
+                         if @drophandler
+                           @drophandler.call(drop)
+                         end
+                       end)
+    end
+
+    # Provide a proc which will be executed when an error record is
+    # received.
+    def errhandler(&block)
+      @errhandler = block
+      @t.err_consumer(proc do |err|
+                        if @errhandler
+                          @errhandler.call(err)
+                        end
+                      end)
+    end
+
+    # Signals that the client wishes to stop consuming trace data. 
+    def finish
+      @t.stop
+      @done = true
+    end
+    
+    # Waits for data from the D program, and yields the records returned
+    # to the block given. Returns when the D program exits.
+    #
+    # Pass a list of classes to restrict the types of data returned,
+    # from:
+    #
+    # * DtraceRecord
+    # * DtracePrintfRecord
+    # * DtraceAggregateSet
+    # * DtraceStackRecord
+    #
+    def consume(*types, &block)
+      filter_types(types)
+      @t.buf_consumer(buf_consumer)
+      begin
+        while(true) do
+          @t.sleep
+          work = @t.work(probe_consumer, rec_consumer(block))
+          if (@done || work > 0)
+            break
+          end
+        end
+      ensure
+        @t.stop
+        @t.work(probe_consumer)
+      end
+    end
+    
+    # Yields the data waiting from the current program, then returns.
+    #
+    # Pass a list of classes to restrict the types of data returned,
+    # from:
+    #
+    # * DtraceRecord
+    # * DtracePrintfRecord
+    # * DtraceAggregateSet
+    # * DtraceStackRecord
+    #
+    def consume_once(*types, &block)
+      filter_types(types)
+      @t.buf_consumer(buf_consumer)
+      @t.stop
+      @t.work(probe_consumer, rec_consumer(block))
+    end
+    
+  end
+end

data/lib/dtrace/data.rb

@@ -0,0 +1,82 @@
+#
+# Ruby-Dtrace
+# (c) 2007 Chris Andrews <chris@nodnol.org>
+#
+# The object returned from a consumer when a probe fires.  Accumulates
+# records from the callbacks, and is yielded when the data is complete.
+class Dtrace
+  class Data
+    attr_reader :data
+    attr_reader :probe
+    attr_reader :cpu, :indent, :prefix, :flow
+
+    def initialize(types)
+      @types = types
+      @data = []
+      @curraggset = nil
+      @curragg    = nil
+    end
+
+    def add_data(d)
+      if @types.length == 0 || @types.include?(d.class)
+        @data << d
+      end
+    end
+
+    def finish
+      if @curraggset
+        add_data(@curraggset)
+        @curraggset = nil
+      end
+    end
+
+    def add_recdata(rec)
+      if @curraggset
+        add_data(@curraggset)
+        @curraggset = nil
+      end
+      if rec.action == "printa"
+        @curraggset = Dtrace::AggregateSet.new
+      end
+    end
+
+    def add_probedata(probedata)
+      probedata.each_record do |p|
+        add_data(p)
+      end
+
+      # Record the probe that fired, and CPU/indent/prefix/flow
+      @probe  = probedata.probe
+      @cpu    = probedata.cpu
+      @indent = probedata.indent
+      @prefix = probedata.prefix
+      @flow   = probedata.flow
+    end
+    
+    def add_bufdata(buf)
+      r = buf.record
+      # buf records can be empty (trace();)
+      if r
+        case r.class.to_s
+        when Dtrace::StackRecord.to_s
+          add_data(r)
+        when Dtrace::Record.to_s
+          add_data(r)
+        when Dtrace::PrintfRecord.to_s
+          add_data(r)
+        when Dtrace::AggData.to_s
+          if @curragg == nil
+            @curragg = Dtrace::Aggregate.new
+          end
+          if agg = @curragg.add_record(r)
+            if @curraggset
+              @curraggset.add_aggregate(@curragg)
+            end
+            @curragg = nil
+          end
+        end
+      end
+    end
+    
+  end
+end

data/lib/dtrace/dof/file.rb

@@ -0,0 +1,63 @@
+#
+# Ruby-Dtrace
+# (c) 2008 Chris Andrews <chris@nodnol.org>
+#
+
+class Dtrace::Dof::File
+  include Dtrace::Dof::Constants
+  attr_accessor :sections
+
+  def initialize
+    @sections = []
+  end
+
+  def generate
+    hdr = Dtrace::Dof::Header.new
+    hdr.secnum = @sections.length
+    filesz = hdr.hdrlen
+    loadsz = filesz
+    dof_version = 1
+
+    @sections.each do |s|
+      # Presence of is_enabled probes forces DOF version 2.
+      if s.section_type == DOF_SECT_PRENOFFS
+        dof_version = 2
+      end
+      
+      length = s.generate
+      s.offset = filesz
+
+      pad = 0
+      if s.align > 1
+        i = s.offset.to_f % s.align
+        if i > 0
+          pad = (s.align - i).to_i
+          s.offset = pad + s.offset
+          s.pad = "\000" * pad
+        end
+      end
+
+      s.size = length + pad
+
+      loadsz += s.size if (s.flags & 1) == 1 # DOF_SECF_LOAD
+      filesz += s.size
+
+    end
+    
+    hdr.loadsz = loadsz
+    hdr.filesz = filesz
+    hdr.dof_version = dof_version
+
+    self << hdr.generate
+    
+    @sections.each do |s|
+      self << s.generate_header
+    end
+      
+    @sections.each do |s|
+      self << s.pad if s.pad
+      self << s.dof
+    end
+  end
+end
+  

data/lib/dtrace/dof/section/strtab.rb

@@ -0,0 +1,21 @@
+#
+# Ruby-Dtrace
+# (c) 2008 Chris Andrews <chris@nodnol.org>
+#
+
+class Dtrace::Dof::Section::Strtab < Dtrace::Dof::Section
+  def initialize(index)
+    super(DOF_SECT_STRTAB, index)
+    self.data = []
+    @idx = 1
+  end
+
+  def add(string)
+    idx = @idx
+    string = string.to_s
+    @idx += (string.length + 1)
+    self.data << string
+    return idx
+  end
+
+end

data/lib/dtrace/dof/section.rb

@@ -0,0 +1,69 @@
+#
+# Ruby-Dtrace
+# (c) 2008 Chris Andrews <chris@nodnol.org>
+#
+
+require 'dtrace/dof/section/strtab'
+
+class Dtrace::Dof::Section
+  include Dtrace::Dof::Constants
+  attr_writer :entsize
+  attr_accessor :flags, :data, :offset, :align, :pad, :size
+  attr_reader :section_type, :dof
+  
+  def initialize(type, index)
+    @section_type  = type
+    @index         = index
+    @flags         = 1 # DOF_SECF_LOAD
+    @data          = {}
+  end
+
+  def generate
+    case @section_type
+    when DOF_SECT_COMMENTS
+      @align = 1
+      @dof = dof_generate_comments
+    when DOF_SECT_STRTAB
+      @align = 1
+      @dof = dof_generate_strtab
+    when DOF_SECT_PROBES
+      @align = 8
+      @dof = dof_generate_probes
+    when DOF_SECT_PRARGS
+      @align = 1
+      @dof = dof_generate_prargs
+    when DOF_SECT_PROFFS
+      @align = 4
+      @dof = dof_generate_proffs
+    when DOF_SECT_PRENOFFS
+      @align = 4
+      @dof = dof_generate_prenoffs
+    when DOF_SECT_PROVIDER
+      @align = 4
+      @dof = dof_generate_provider
+    when DOF_SECT_RELTAB
+      @align = 8
+      @dof = dof_generate_reltab
+    when DOF_SECT_URELHDR
+      @align = 4
+      @dof = dof_generate_relhdr
+    when DOF_SECT_UTSNAME
+      @align = 1
+      @dof = dof_generate_utsname
+    else
+      @dof = ''
+    end
+
+    begin
+      if @data.class == Array
+        @entsize = @dof.length / @data.length
+      else
+        @entsize = 0
+      end
+    rescue ZeroDivisionError
+      @entsize = 0
+    end
+
+    return @dof.length
+  end
+end

data/lib/dtrace/dof.rb

@@ -0,0 +1,8 @@
+#
+# Ruby-Dtrace
+# (c) 2008 Chris Andrews <chris@nodnol.org>
+#
+
+require 'dof/dof_api'
+require 'dtrace/dof/section'
+require 'dtrace/dof/file'

data/lib/dtrace/printfrecord.rb

@@ -0,0 +1,10 @@
+#
+# Ruby-Dtrace
+# (c) 2007 Chris Andrews <chris@nodnol.org>
+#
+# A DTrace record for the formatted part of a printf() action. 
+class Dtrace
+  class PrintfRecord
+    attr_accessor :value
+  end
+end

data/lib/dtrace/probe.rb

@@ -0,0 +1,46 @@
+#
+# Ruby-Dtrace
+# (c) 2008 Chris Andrews <chris@nodnol.org>
+
+class Dtrace
+  # 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/probedata.rb

@@ -0,0 +1,23 @@
+#
+# Ruby-Dtrace
+# (c) 2007 Chris Andrews <chris@nodnol.org>
+#
+
+class Dtrace
+  class ProbeData
+    
+    def records
+      records = Array.new
+      self.each_record do |rec|
+        records << rec
+      end
+      records
+    end
+
+    def to_s
+      rs = self.records
+      rs.map {|r| r.value }.join ', '
+    end
+
+  end
+end

data/lib/dtrace/probedesc.rb

@@ -0,0 +1,15 @@
+#
+# Ruby-Dtrace
+# (c) 2007 Chris Andrews <chris@nodnol.org>
+#
+
+class Dtrace
+  class ProbeDesc
+    
+    def to_s
+      "#{provider}:#{mod}:#{func}:#{name}"
+    end
+
+  end
+end
+    

data/lib/dtrace/provider/probedef.rb

@@ -0,0 +1,24 @@
+#
+# Ruby-Dtrace
+# (c) 2008 Chris Andrews <chris@nodnol.org>
+#
+
+class Dtrace
+  class Provider
+    class ProbeDef
+      attr_reader :name, :function
+      attr_accessor :args
+
+      def initialize(name, function)
+        @name = name.to_s
+        @function = function.to_s
+        @args = []
+      end
+
+      def argc
+        @args.length
+      end
+
+    end
+  end
+end