ruby-usdt 0.1.2 → 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 32ca9d27b82e9e04dc7c82c91841ba967dea40d8
+  data.tar.gz: 90ea9c2c69fbc5311ea9da9992d0f7339ee5d9c6
+SHA512:
+  metadata.gz: 27df55c3cafad792beaa5f0858a6abd624d6c57708f79efb41d4ab2fe422429ac928dc18f234b4fce44b2ced1086021990b2ea7d55fe0f4a750827aa56a02a70
+  data.tar.gz: a909999ff4e99cca642386a96388f2838edeb5c4765176280734e9aedca964c41eb22a8d66d4331ca979e0403e749144d35d81ad49e5057e6df8865d3a84b4b4

data/README.md

@@ -10,47 +10,65 @@ providers at runtime for instrumentation and analysis by the
 
 ### Install
 
-    gem install ruby-usdt
+```ruby
+gem install ruby-usdt
+```
 
 When using Bundler to integrate ruby-usdt into a Ruby or Rails project,
 you will need to specify that there are git submodule dependencies:
 
-    gem "ruby-usdt", :submodules => true
+```ruby
+gem "ruby-usdt", :submodules => true
+```
 
 ### Usage
 
-    # Provider.create <provider>, <module>
-    #
-    # Creates a probe
-    #
-    # returns USDT::Provider object
-    provider = USDT::Provider.create :ruby, :mymod
-
-    # Provider#probe *args
-    #
-    # args must be either :integer, or :string
-    # max 6 args (dtrace provides this many), additional args will be ignored
-    # returns USDT::Probe object
-    p = provider.probe(:myfn, :probe, :string, :string, :integer)
-
-    # Provider#enable
-    # enables the probes defined with #probe
-    provider.enable
-
-    while true
-      if p.enabled?
-        p.fire("omg", "probe!!", 12345)
-      end
-      sleep 0.5
-    end
-
-    # see the probes in action with:
-    # you should see continious output of the fire args above
-    sudo dtrace -n 'ruby*:mymod:myfn:probe { printf("%s %s %d",
-      copyinstr(arg0),
-      copyinstr(arg1),
-      args[2])
-    }'
+```ruby
+# Provider.create <provider>, <module>
+#
+# Creates a probe
+#
+# returns USDT::Provider object
+provider = USDT::Provider.create :ruby, :mymod
+
+# Provider#probe *args
+#
+# args must be either :integer, or :string
+# max 6 args (dtrace provides this many), additional args will be ignored
+# returns USDT::Probe object
+probe = provider.probe(:myfn, :probe, :string, :string, :integer)
+
+# Provider#enable
+# enables the probes defined with #probe
+provider.enable
+
+while true
+  if probe.enabled?
+    probe.fire("omg", "probe!!", 12345)
+  end
+  sleep 0.5
+end
+```
+
+To see the above probe working, the following dtrace script can be used:
+```bash
+sudo dtrace -n 'ruby*:mymod:myfn:probe { printf("%s %s %d",
+  copyinstr(arg0),
+  copyinstr(arg1),
+  args[2])
+}'
+```
+
+### Probes in Ruby
+
+Introspection can be done on a probe from within Ruby using the
+following commands:
+
+```ruby
+probe.function  => :myfn
+probe.name      => :probe
+probe.arguments => [:string, :string, :integer]
+```
 
 ## Additional Resources
 

data/ext/usdt/test.rb

@@ -1,12 +1,29 @@
 require File.expand_path(File.dirname(__FILE__)) + '/usdt'
 
+puts "## Provider"
 provider = USDT::Provider.create :ruby, :test
 puts provider
-p = provider.probe(:myfn, :probe,
+
+puts
+puts "## Probe with sym definition"
+probe = provider.probe(:myfn, :probe,
                    :string, :string, :integer)
+puts probe
+puts "probe.function: #{probe.function.inspect}"
+puts "probe.name: #{probe.name.inspect}"
+puts "probe.arguments: #{probe.arguments.inspect}"
+
+puts
+puts "## Probe with string definition"
+probe_str = provider.probe('myfn', 'str', :string)
+puts probe_str
+puts "probe.function: #{probe_str.function.inspect}"
+puts "probe.name: #{probe_str.name.inspect}"
+puts "probe.arguments: #{probe_str.arguments.inspect}"
 
 provider.enable
 
+puts
 puts "run:\nsudo dtrace -n 'ruby*:test:myfn:probe { printf(\"%s %s %d\",
   copyinstr(arg0),
   copyinstr(arg1),
@@ -14,8 +31,8 @@ puts "run:\nsudo dtrace -n 'ruby*:test:myfn:probe { printf(\"%s %s %d\",
 }'"
 
 while true
-  if p.enabled? 
-    p.fire("one", "two", 3)
+  if probe.enabled? 
+    probe.fire("one", "two", 3)
     puts("Fired!")
   end
   sleep 0.5

data/ext/usdt/usdt.c

@@ -13,6 +13,9 @@ static VALUE provider_enable(VALUE self);
 static VALUE provider_disable(VALUE self);
 static VALUE probe_enabled(VALUE self);
 static VALUE probe_fire(int argc, VALUE *argv, VALUE self);
+static VALUE probe_function(VALUE self);
+static VALUE probe_name(VALUE self);
+static VALUE probe_args(VALUE self);
 
 void Init_usdt() {
   USDT = rb_define_module("USDT");
@@ -29,6 +32,9 @@ void Init_usdt() {
   USDT_Probe = rb_define_class_under(USDT, "Probe", rb_cObject);
   rb_define_method(USDT_Probe, "enabled?", probe_enabled, 0);
   rb_define_method(USDT_Probe, "fire", probe_fire, -1);
+  rb_define_method(USDT_Probe, "function", probe_function, 0);
+  rb_define_method(USDT_Probe, "name", probe_name, 0);
+  rb_define_method(USDT_Probe, "arguments", probe_args, 0);
 }
 
 /**
@@ -177,3 +183,43 @@ static VALUE probe_fire(int argc, VALUE *argv, VALUE self) {
   usdt_fire_probe(probedef->probe, probedef->argc, pargs);
   return Qtrue;
 }
+
+/**
+ * USDT::Probe#function
+ */
+static VALUE probe_function(VALUE self) {
+  usdt_probedef_t **p = DATA_PTR(self);
+  usdt_probedef_t *probedef = *p;
+  return ID2SYM(rb_intern(probedef->function));
+}
+
+/**
+ * USDT::Probe#name
+ */
+static VALUE probe_name(VALUE self) {
+  usdt_probedef_t **p = DATA_PTR(self);
+  usdt_probedef_t *probedef = *p;
+  return ID2SYM(rb_intern(probedef->name));
+}
+
+/**
+ * USDT::Probe#arguments
+ */
+static VALUE probe_args(VALUE self) {
+  usdt_probedef_t **p = DATA_PTR(self);
+  usdt_probedef_t *probedef = *p;
+
+  VALUE args = rb_ary_new();
+  size_t i;
+
+  for (i = 0; i < probedef->argc; i++) {
+    if (probedef->types[i] == USDT_ARGTYPE_STRING) {
+      rb_ary_push(args, ID2SYM(rb_intern("string")));
+    } else if (probedef->types[i] == USDT_ARGTYPE_INTEGER) {
+      rb_ary_push(args, ID2SYM(rb_intern("integer")));
+    } else {
+      rb_ary_push(args, Qnil);
+    }
+  }
+  return args;
+}

data/lib/usdt/version.rb

@@ -1,3 +1,3 @@
 module USDT
-  VERSION = '0.1.2'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-usdt
 version: !ruby/object:Gem::Version
-  version: 0.1.2
-  prerelease: 
+  version: 0.2.0
 platform: ruby
 authors:
 - Kevin Chan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-13 00:00:00.000000000 Z
+date: 2013-11-08 00:00:00.000000000 Z
 dependencies: []
 description: 
 email:
@@ -21,51 +20,34 @@ extra_rdoc_files: []
 files:
 - lib/usdt/version.rb
 - lib/usdt.rb
-- ext/libusdt/LICENCE
-- ext/libusdt/Makefile
-- ext/libusdt/README.md
-- ext/libusdt/test.pl
-- ext/libusdt/test_mem_usage.c
-- ext/libusdt/test_usdt.c
-- ext/libusdt/usdt.c
-- ext/libusdt/usdt.h
-- ext/libusdt/usdt_dof.c
-- ext/libusdt/usdt_dof_file.c
-- ext/libusdt/usdt_dof_sections.c
-- ext/libusdt/usdt_internal.h
-- ext/libusdt/usdt_probe.c
-- ext/libusdt/usdt_tracepoints_i386.s
-- ext/libusdt/usdt_tracepoints_x86_64.s
 - ext/usdt/extconf.rb
-- ext/usdt/Makefile
 - ext/usdt/test.rb
 - ext/usdt/usdt.c
-- ext/usdt/usdt.h
 - README.md
 - LICENSE.md
 homepage: http://github.com/kevinykchan/ruby-usdt
 licenses: []
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 - ext
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.21
+rubygems_version: 2.0.5
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Native DTrace probes for ruby.
 test_files: []
+has_rdoc: 

data/ext/libusdt/LICENCE

@@ -1,21 +0,0 @@
-Copyright 2012 Chris Andrews. All rights reserved.
-
-Redistribution and use in source and binary forms, with or without modification, are
-permitted provided that the following conditions are met:
-
-   1. Redistributions of source code must retain the above copyright notice, this list of
-      conditions and the following disclaimer.
-
-   2. Redistributions in binary form must reproduce the above copyright notice, this list
-      of conditions and the following disclaimer in the documentation and/or other materials
-      provided with the distribution.
-
-THIS SOFTWARE IS PROVIDED BY CHRIS ANDREWS ``AS IS'' AND ANY EXPRESS OR IMPLIED
-WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
-FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL CHRIS ANDREWS OR
-CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
-ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
-NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
-ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/ext/libusdt/Makefile

@@ -1,148 +0,0 @@
-CC = gcc
-CFLAGS = -O2
-
-# MAC_BUILD - set this to "universal" to build a 2-way fat library 
-MAC_BUILD = universal
-
-# if ARCH set, disable universal build on the mac
-ifdef ARCH
-MAC_BUILD =
-else
-ARCH = $(shell uname -m)
-endif
-
-UNAME = $(shell uname -s)
-
-ifeq ($(UNAME), SunOS)
-RANLIB=/bin/true
-PATH +=:/usr/perl5/5.10.0/bin:/usr/perl5/5.12/bin
-CFLAGS += -fPIC
-
-ifeq ($(ARCH), i86pc)
-ARCH = $(shell isainfo -k)
-ifeq ($(ARCH), amd64)
-ARCH = x86_64
-else
-ARCH = i386
-endif
-endif 
-ifeq ($(ARCH), x86_64)
-CFLAGS += -m64
-endif
-endif
-
-ifeq ($(UNAME), FreeBSD)
-RANLIB=ranlib
-CFLAGS += -Wno-error=unknown-pragmas -I/usr/src/sys/cddl/compat/opensolaris -I/usr/src/sys/cddl/contrib/opensolaris/uts/common
-ifeq ($(ARCH), i386)
-CFLAGS += -m32
-endif
-endif
-
-ifeq ($(UNAME), Darwin)
-RANLIB=ranlib
-ifeq ($(MAC_BUILD), universal)
-CFLAGS += -arch i386 -arch x86_64
-else
-CFLAGS += -arch $(ARCH)
-endif
-endif
-
-# main library build
-objects = usdt.o usdt_dof_file.o usdt_tracepoints.o usdt_probe.o usdt_dof.o usdt_dof_sections.o
-headers = usdt.h usdt_internal.h
-
-.c.o: $(headers)
-
-all: libusdt.a
-
-libusdt.a: $(objects) $(headers)
-	rm -f libusdt.a
-	$(AR) cru libusdt.a $(objects) 
-	$(RANLIB) libusdt.a
-
-# Tracepoints build. 
-#
-# If on Darwin and building a universal library, manually assemble a
-# two-way fat object file from both the 32 and 64 bit tracepoint asm
-# files.
-#
-# Otherwise, just choose the appropriate asm file based on the build
-# architecture.
-
-ifeq ($(UNAME), Darwin)
-ifeq ($(MAC_BUILD), universal)
-
-usdt_tracepoints_i386.o: usdt_tracepoints_i386.s
-	$(CC) -arch i386 -o usdt_tracepoints_i386.o -c usdt_tracepoints_i386.s
-
-usdt_tracepoints_x86_64.o: usdt_tracepoints_x86_64.s
-	$(CC) -arch x86_64 -o usdt_tracepoints_x86_64.o -c usdt_tracepoints_x86_64.s
-
-usdt_tracepoints.o: usdt_tracepoints_i386.o usdt_tracepoints_x86_64.o
-	lipo -create -output usdt_tracepoints.o usdt_tracepoints_i386.o \
-	                                        usdt_tracepoints_x86_64.o
-
-else # Darwin, not universal
-usdt_tracepoints.o: usdt_tracepoints_$(ARCH).s
-	$(CC) -arch $(ARCH) -o usdt_tracepoints.o -c usdt_tracepoints_$(ARCH).s
-endif
-
-else # not Darwin; FreeBSD and Illumos
-
-ifeq ($(ARCH), x86_64)
-usdt_tracepoints.o: usdt_tracepoints_x86_64.s
-	$(CC) $(CFLAGS) -o usdt_tracepoints.o -c usdt_tracepoints_x86_64.s
-endif
-ifeq ($(ARCH), i386)
-usdt_tracepoints.o: usdt_tracepoints_i386.s
-	$(CC) $(CFLAGS) -o usdt_tracepoints.o -c usdt_tracepoints_i386.s
-endif
-
-endif
-
-clean:
-	rm -f *.gch
-	rm -f *.o
-	rm -f libusdt.a
-	rm -f test_usdt
-	rm -f test_usdt32
-	rm -f test_usdt64
-	rm -f test_mem_usage
-
-.PHONY: clean test
-
-# testing
-
-test_mem_usage: libusdt.a test_mem_usage.o
-	$(CC) $(CFLAGS) -o test_mem_usage test_mem_usage.o libusdt.a 
-
-ifeq ($(UNAME), Darwin)
-ifeq ($(MAC_BUILD), universal)
-test_usdt64: libusdt.a test_usdt.o
-	$(CC) -arch x86_64 -o test_usdt64 test_usdt.o libusdt.a
-test_usdt32: libusdt.a test_usdt.o
-	$(CC) -arch i386 -o test_usdt32 test_usdt.o libusdt.a
-else
-test_usdt: libusdt.a test_usdt.o
-	$(CC) $(CFLAGS) -o test_usdt test_usdt.o libusdt.a 
-endif
-else
-test_usdt: libusdt.a test_usdt.o
-	$(CC) $(CFLAGS) -o test_usdt test_usdt.o libusdt.a 
-endif
-
-ifeq ($(UNAME), Darwin)
-ifeq ($(MAC_BUILD), universal)
-test: test_usdt32 test_usdt64
-	sudo prove test.pl :: 64
-	sudo prove test.pl :: 32
-else
-test: test_usdt
-	sudo prove test.pl
-endif
-else
-test: test_usdt
-	sudo prove test.pl
-endif
-

data/ext/libusdt/README.md

@@ -1,81 +0,0 @@
-libusdt
-=======
-
-This is "libusdt", an extraction into a C library of the common parts
-of ruby-dtrace[1], perl-dtrace[2] and node-dtrace-provider[3].
-
-Those individual language-specific implementations will then become
-bindings to this library, rather than containing their own
-implementations of DOF generation and probe creation. Other dynamic
-language bindings could then easily follow.
-
-The idea here is to allow the specification of a DTrace provider
-dynamically in code and then create the provider at runtime. This
-allows providers to be specified in dynamic languages, given suitable
-bindings.
-
-The general approach is to create two stub functions for each probe,
-one for the is-enabled check and one for the probe itself. These
-contain the appropriate instruction sequences to appear to DTrace as
-compiled-in tracepoints. A minimal DOF document is built describing
-the provider and indicating these stub functions as the tracepoints,
-then submitted to the kernel, creating the provider. The API then
-exposes the stubs, through which the probes may be fired.
-
-Status
-------
-
-The implementation here works as shown in test_usdt.c on Mac OS X,
-i386 and x86_64, on Solaris-like systems, i386 and x86_64 and on
-FreeBSD, x86_64 only (so far).
-
-Is-enabled probes are supported and exposed in the API.
-
-There is a "test" target which runs a number of tests of the library,
-for which perl is required.
-
-OS X builds are Universal by default, and on Solaris, the ARCH
-variable may be set to either i386 or x86_64 to force a particular
-build.
-
-FreeBSD builds suffer from broken argument handling; this is a known
-issue with the current state of DTrace generally on FreeBSD: only the
-first four arguments work reliably. See:
-
-  http://wiki.freebsd.org/DTraceTODO
-
-See Also
---------
-
-There are experimental Lua bindings available, which are a thin
-layer over this library, and should serve as an example of typical use
-as a dynamic language extension:
-
-  https://github.com/chrisa/lua-usdt
-
-There are also Ruby bindings by Kevin Chan, replacing the provider
-implementation in ruby-dtrace:
-
-  https://github.com/kevinykchan/ruby-usdt
-
-To Do
------
-
-Platform support:
-
- * add support for FreeBSD 9.0 i386
- * add support for Mac OS X PowerPC
- * add support for Solaris SPARC
-
-Features:
-
- * add a "low level" API, allowing alternative provision of
-   tracepoints for closer integration with language VMs. 
-
- * support structured types, with close integration with the host
-   DTrace system.
-
-
-[1] https://github.com/chrisa/ruby-dtrace
-[2] https://github.com/chrisa/perl-dtrace
-[3] https://github.com/chrisa/node-dtrace-provider

data/ext/libusdt/test.pl

@@ -1,112 +0,0 @@
-#!/usr/bin/perl
-use strict;
-use warnings;
-use IPC::Open3;
-use Symbol 'gensym'; 
-use IO::Handle;
-use Test::More qw/ no_plan /;
-
-my $USDT_ARG_MAX = 32;
-
-my $arch;
-if (scalar @ARGV == 1) {
-    $arch = $ARGV[0];
-}
-
-my $user_t = ($^O eq 'solaris') ? 'uintptr_t' : 'user_addr_t';
-
-run_tests('c', 'A');
-run_tests('i', 1);
-
-sub run_tests {
-    my ($type, $start_arg) = @_;
-    
-    for my $i (0..$USDT_ARG_MAX) {
-        my ($t_status, $d_status, $output) = run_dtrace('func', 'name', split(//, $type x $i));
-        is($t_status, 0, 'test exit status is 0');
-        is($d_status, 0, 'dtrace exit status is 0');
-        like($output, qr/func:name/, 'function and name match');
-
-        my $arg = $start_arg;
-        for my $j (0..$i - 1) {
-            like($output, qr/arg$j:'\Q$arg\E'/, "type '$type' arg $j is $arg");
-            if ($type eq 'i') {
-                $arg++;
-            }
-            else {
-                $arg = chr(ord($arg) + 1);
-            }
-        }
-    }
-}
-
-# --------------------------------------------------------------------------
-
-sub gen_d {
-    my (@types) = @_;
-
-    my $d = 'testlibusdt*:::{ ';
-    my $i = 0;
-    for my $type (@types) {
-        if ($type eq 'i') {
-            $d .= "printf(\"arg$i:'%i' \", args[$i]); ";
-        }
-        if ($type eq 'c') {
-            $d .= "printf(\"arg$i:'%s' \", copyinstr(($user_t)args[$i])); ";
-        }
-        $i++;
-    }
-    $d .= '}';
-
-    return $d;
-}
-         
-sub run_dtrace {
-    my ($func, $name, @types) = @_;
-    my $d = gen_d(@types);
-
-    my @t_cmd;
-    if (defined $arch) {
-        @t_cmd = ("./test_usdt$arch", $func, $name, @types);
-    }
-    else {
-        @t_cmd = ("./test_usdt", $func, $name, @types);
-    }
-
-    my ($d_wtr, $d_rdr, $d_err);
-    my ($t_wtr, $t_rdr, $t_err);
-
-    $d_err = gensym;
-    $t_err = gensym;
-
-    #diag(join(' ', @t_cmd));
-    my $t_pid = open3($t_wtr, $t_rdr, $t_err, @t_cmd);
-    my $enabled = $t_rdr->getline;
-
-    my @d_cmd = ('/usr/sbin/dtrace', '-p', $t_pid, '-n', $d);
-
-    #diag(join(' ', @d_cmd));
-    my $d_pid = open3($d_wtr, $d_rdr, $d_err, @d_cmd);
-    my $matched = $d_err->getline; # expect "matched 1 probe"
-
-    $t_wtr->print("go\n");
-    $t_wtr->flush;
-    waitpid( $t_pid, 0 );
-    my $t_status = $? >> 8;
-
-    my ($header, $output) = ($d_rdr->getline, $d_rdr->getline);
-    chomp $header;
-    chomp $output;
-    #diag("DTrace header: $header\n");
-    #diag("DTrace output: $output\n");
-    waitpid( $d_pid, 0 );
-
-    my $d_status = $? >> 8;
-    while (!$d_err->eof) {
-        my $error = $d_err->getline;
-        chomp $error;
-        #diag "DTrace error: $error";
-    }
-
-    return ($t_status, $d_status, $output || '');
-}