ruby-dtrace 0.0.6 → 0.2.8

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.rb

@@ -4,15 +4,17 @@
 #
 
 require 'dtrace_api'
-require 'dtracerecord'
+require 'dtrace/record'
+require 'dtrace/consumer'
 require 'dtraceconsumer'
-require 'dtraceaggregate'
-require 'dtraceaggregateset'
-require 'dtraceprobedata'
-require 'dtraceprobe'
-require 'dtracestackrecord'
-require 'dtraceprintfrecord'
-require 'dtracedata'
+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
@@ -22,10 +24,10 @@ require 'dtracedata'
 #
 # * Create a handle with Dtrace.new
 # * Set options
-# * Compile the program, possibly inspecting the return DtraceProgramInfo
+# * 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 DtraceConsumer.
+# * Consume data, either directly by setting up callbacks, or using a Dtrace::Consumer.
 # * Stop tracing
 #
 # === Listing probes
@@ -57,18 +59,37 @@ require 'dtracedata'
 #   t.go
 #   p.continue
 #
-#   c = DtraceConsumer.new(t)
+#   c = Dtrace::Consumer.new(t)
 #   c.consume do |d|
 #     ..
 #   end
 
 class Dtrace
-  VERSION = '0.0.6'
-
   STATUS_NONE    = 0
   STATUS_OKAY    = 1
   STATUS_EXITED  = 2
   STATUS_FILLED  = 3
   STATUS_STOPPED = 4
+
+  # Yields each probe on the system, optionally matching against a
+  # probe specification:
+  # 
+  # e.g.
+  # syscall:::      -> all probes in the syscall provider
+  # pid123:::return -> all return probes in pid 123.
+  #
+  def each_probe(match=nil, &block)
+    if match
+      parts = match.split(':', 4)
+      begin
+        each_probe_match(*parts, &block)
+      rescue ArgumentError => e
+        raise Dtrace::Exception.new("each_probe: probe specification expected (e.g. 'provider:::')")
+      end
+    else
+      each_probe_all(&block)
+    end
+  end
+
 end
 

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