ruby-dtrace-consumer 0.4.0

data/ext/dtrace_programinfo.c~

@@ -0,0 +1,60 @@
+/* Ruby-DTrace
+ * (c) 2007 Chris Andrews <chris@nodnol.org>
+ */
+
+#include "dtrace_api.h"
+
+/* :nodoc: */
+VALUE dtraceprograminfo_init(VALUE self)
+{
+  dtrace_proginfo_t *proginfo;
+
+  Data_Get_Struct(self, dtrace_proginfo_t, proginfo);
+  return self;
+}
+
+/*
+ * Returns the number of aggregates associated with this program.
+ */
+VALUE dtraceprograminfo_aggregates_count(VALUE self) 
+{
+  dtrace_proginfo_t *proginfo;
+
+  Data_Get_Struct(self, dtrace_proginfo_t, proginfo);
+  return INT2NUM(proginfo->dpi_aggregates);
+}
+
+/*
+ * Returns the number of record generating probes associated with this
+ * program.
+ */
+VALUE dtraceprograminfo_recgens_count(VALUE self)
+{
+  dtrace_proginfo_t *proginfo;
+
+  Data_Get_Struct(self, dtrace_proginfo_t, proginfo);
+  return INT2NUM(proginfo->dpi_recgens);
+}
+
+/*
+ * Returns the number of probes matched by this program.
+ */
+VALUE dtraceprograminfo_matches_count(VALUE self)
+{
+  dtrace_proginfo_t *proginfo;
+
+  Data_Get_Struct(self, dtrace_proginfo_t, proginfo);
+  return INT2NUM(proginfo->dpi_matches);
+}
+
+/*
+ * Returns the number of speculations specified by this program.
+ */
+VALUE dtraceprograminfo_speculations_count(VALUE self)
+{
+  dtrace_proginfo_t *proginfo;
+
+  Data_Get_Struct(self, dtrace_proginfo_t, proginfo);
+  return INT2NUM(proginfo->dpi_speculations);
+}
+

data/ext/dtrace_recdesc.c

@@ -0,0 +1,37 @@
+/* Ruby-DTrace
+ * (c) 2007 Chris Andrews <chris@nodnol.org>
+ */
+
+#include "dtrace_api.h"
+
+/*
+ * Returns the type of action which generated this recdesc.
+ * (exit, printf, printa or "other" for all other actions).
+ */
+VALUE dtracerecdesc_action(VALUE self)
+{
+  dtrace_recdesc_t *recdesc;
+  VALUE v;
+  Data_Get_Struct(self, dtrace_recdesc_t, recdesc);
+
+  if (recdesc){
+    switch (recdesc->dtrd_action) {
+    case DTRACEACT_EXIT:
+      v = rb_str_new2("exit");
+      break;
+    case DTRACEACT_PRINTF:
+      v = rb_str_new2("printf");
+      break;
+    case DTRACEACT_PRINTA:
+      v = rb_str_new2("printa");
+      break;
+    default:
+      v = rb_str_new2("other");
+      break;
+    }
+    return v;
+  }
+  else {
+    return Qnil;
+  }
+}

data/ext/dtrace_recdesc.c~

@@ -0,0 +1,46 @@
+/* Ruby-DTrace
+ * (c) 2007 Chris Andrews <chris@nodnol.org>
+ */
+
+#include "dtrace_api.h"
+
+/* :nodoc: */
+VALUE dtracerecdesc_init(VALUE self)
+{
+  dtrace_recdesc_t *recdesc;
+
+  Data_Get_Struct(self, dtrace_recdesc_t, recdesc);
+  return self;
+}
+
+/*
+ * Returns the type of action which generated this recdesc.
+ * (exit, printf, printa or "other" for all other actions).
+ */
+VALUE dtracerecdesc_action(VALUE self)
+{
+  dtrace_recdesc_t *recdesc;
+  VALUE v;
+  Data_Get_Struct(self, dtrace_recdesc_t, recdesc);
+
+  if (recdesc){
+    switch (recdesc->dtrd_action) {
+    case DTRACEACT_EXIT:
+      v = rb_str_new2("exit");
+      break;
+    case DTRACEACT_PRINTF:
+      v = rb_str_new2("printf");
+      break;
+    case DTRACEACT_PRINTA:
+      v = rb_str_new2("printa");
+      break;
+    default:
+      v = rb_str_new2("other");
+      break;
+    }
+    return v;
+  }
+  else {
+    return Qnil;
+  }
+}

data/ext/dtrace_util.c

@@ -0,0 +1,92 @@
+/* Ruby-DTrace
+ * (c) 2007 Chris Andrews <chris@nodnol.org>
+ */
+
+#include "dtrace_api.h"
+#include <ctype.h>
+
+RUBY_EXTERN VALUE eDTraceException;
+
+/*
+ * Most of this function lifted from libdtrace/common/dt_consume.c
+ * dt_print_bytes().
+ */
+VALUE handle_bytedata(caddr_t addr, uint32_t nbytes)
+{
+  /*
+   * If the byte stream is a series of printable characters, followed by
+   * a terminating byte, we print it out as a string.  Otherwise, we
+   * assume that it's something else and just print the bytes.
+   */
+  int i, j;
+  char *c = addr;
+
+  VALUE robj;
+
+  if (nbytes == 0) {
+    return rb_str_new2("");
+  }
+
+  for (i = 0; i < nbytes; i++) {
+    /*
+     * We define a "printable character" to be one for which
+     * isprint(3C) returns non-zero, isspace(3C) returns non-zero,
+     * or a character which is either backspace or the bell.
+     * Backspace and the bell are regrettably special because
+     * they fail the first two tests -- and yet they are entirely
+     * printable.  These are the only two control characters that
+     * have meaning for the terminal and for which isprint(3C) and
+     * isspace(3C) return 0.
+     */
+    if (isprint(c[i]) || isspace(c[i]) ||
+	c[i] == '\b' || c[i] == '\a')
+      continue;
+
+    if (c[i] == '\0' && i > 0) {
+      /*
+       * This looks like it might be a string.  Before we
+       * assume that it is indeed a string, check the
+       * remainder of the byte range; if it contains
+       * additional non-nul characters, we'll assume that
+       * it's a binary stream that just happens to look like
+       * a string.
+       */
+      for (j = i + 1; j < nbytes; j++) {
+	if (c[j] != '\0')
+	  break;
+      }
+
+      if (j != nbytes)
+	break;
+
+      /* It's a string */
+      return (rb_str_new2((char *)addr));
+    }
+
+    break;
+  }
+
+  if (i == nbytes) {
+    /*
+     * The byte range is all printable characters, but there is
+     * no trailing nul byte.  We'll assume that it's a string.
+     */
+    char *s = malloc(nbytes + 1);
+    if (!s) {
+      rb_raise(eDTraceException, "out of memory: failed to allocate string value");
+      return (Qnil);
+    }
+    (void) strncpy(s, c, nbytes);
+    s[nbytes] = '\0';
+    robj = rb_str_new2(s);
+    free(s);
+    return (robj);
+  }
+
+  /* return byte array */
+  robj = rb_ary_new();
+  for (i = 0; i < nbytes; i++)
+    rb_ary_push(robj, INT2FIX(addr[i]));
+
+  return (robj);
+}  

data/ext/extconf.rb

@@ -0,0 +1,7 @@
+require 'mkmf'
+require 'rbconfig'
+
+# Need to specify full path to dtrace.h or we'll pick up ruby's
+# dtrace.h on Solaris or other builds with the runtime probes included.
+have_library("dtrace", "dtrace_open", "/usr/include/dtrace.h")
+create_makefile("dtrace_api")

data/lib/dtrace.rb

@@ -0,0 +1,95 @@
+#
+# 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
+
+  # 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