ruby-usdt 0.0.1

data/LICENSE.md

@@ -0,0 +1,18 @@
+Copyright (C) 2012 Kevin Chan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,75 @@
+# ruby-usdt
+
+Ruby bindings for [libusdt](https://github.com/chrisa/libusdt).
+
+Applications, Libraries, and Frameworks can consume ruby-usdt to define USDT  
+providers at runtime for instrumentation and analysis by the DTrace
+[DTrace](http://en.wikipedia.org/wiki/DTrace) framework.
+
+### Install
+
+    gem install ruby-usdt
+
+### 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])
+    }'
+    
+## Additional Resources
+
+- [User-Level-Statically Defined Tracing](http://www.solarisinternals.com/wiki/index.php/DTrace_Topics_USDT#USDT)
+- [DTrace Book](http://www.dtracebook.com/index.php/Main_Page)
+- [Libusdt - Creating DTrace Providers at Runtime](http://chrisa.github.com/blog/2011/12/04/libusdt-runtime-dtrace-providers/)
+
+## License
+
+The MIT License
+
+Copyright (C) 2012 Kevin Chan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/ext/libusdt/Makefile

@@ -0,0 +1,117 @@
+UNAME=$(shell uname)
+ARCH=$(shell uname -m)
+
+MAC_BUILD=universal
+CFLAGS= -g -O0 -Wall -Werror
+CC=cc
+
+ifeq ($(UNAME), SunOS)
+PATH +=:/usr/perl5/5.10.0/bin
+ifeq ($(ARCH), x86_64)
+CFLAGS += -m64
+endif
+endif
+
+ifeq ($(UNAME), FreeBSD)
+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
+
+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
+
+ifeq ($(UNAME), Darwin)
+ifeq ($(MAC_BUILD), universal)
+CFLAGS+= -arch i386 -arch x86_64
+
+usdt_tracepoints_i386.o: usdt_tracepoints_i386.s
+	as -arch i386 -o usdt_tracepoints_i386.o usdt_tracepoints_i386.s
+
+usdt_tracepoints_x86_64.o: usdt_tracepoints_x86_64.s
+	as -arch x86_64 -o usdt_tracepoints_x86_64.o 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
+
+ifeq ($(ARCH), x86_64)
+usdt_tracepoints.o: usdt_tracepoints_x86_64.s
+	as -o usdt_tracepoints.o usdt_tracepoints_x86_64.s
+else
+usdt_tracepoints.o: usdt_tracepoints_i386.s
+	as -o usdt_tracepoints.o usdt_tracepoints_i386.s
+endif
+
+endif
+endif
+
+ifeq ($(UNAME), FreeBSD)
+ifeq ($(ARCH), amd64)
+usdt_tracepoints.o: usdt_tracepoints_x86_64.s
+	as --64 -o usdt_tracepoints.o usdt_tracepoints_x86_64.s
+else
+usdt_tracepoints.o: usdt_tracepoints_i386.s
+	as --32 -o usdt_tracepoints.o usdt_tracepoints_i386.s
+endif
+endif
+
+ifeq ($(UNAME), SunOS)
+ifeq ($(ARCH), x86_64)
+usdt_tracepoints.o: usdt_tracepoints_x86_64.s
+	as --64 -o usdt_tracepoints.o usdt_tracepoints_x86_64.s
+else
+usdt_tracepoints.o: usdt_tracepoints_i386.s
+	as --32 -o usdt_tracepoints.o usdt_tracepoints_i386.s
+endif
+endif
+
+libusdt.a: $(objects) $(headers)
+	ar cru libusdt.a $(objects) 
+	ranlib 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
+
+clean:
+	rm -f *.gch
+	rm -f *.o
+	rm -f libusdt.a
+	rm -f fat_libusdt.a
+	rm -f test_usdt
+	rm -f test_usdt32
+	rm -f test_usdt64
+
+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
+
+.PHONY: clean test

data/ext/libusdt/README

@@ -0,0 +1,59 @@
+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
+
+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. 
+
+[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

@@ -0,0 +1,83 @@
+#!/usr/bin/perl
+use strict;
+use warnings;
+use IPC::Open3;
+use Symbol 'gensym'; 
+use IO::Handle;
+use Test::More qw/ no_plan /;
+
+my $arch;
+if (scalar @ARGV == 1) {
+    $arch = $ARGV[0];
+}
+
+run_tests('c', 'a');
+run_tests('i', 1);
+
+sub run_tests {
+    my ($type, $start_arg) = @_;
+    
+    for my $i (0..6) {
+        my ($status, $output) = run_dtrace('func', 'name', split(//, $type x $i));
+        is($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:'$arg'/, "type '$type' arg $j is $arg");
+            $arg++;
+        }
+    }
+}
+
+# --------------------------------------------------------------------------
+
+sub gen_d {
+    my (@types) = @_;
+
+    my $d = 'testlibusdt*:::{ ';
+    my $i = 0;
+    for my $type (@types) {
+        if ($type eq 'i') {
+            $d .= "printf(\"arg$i:'%i' \", arg$i); ";
+        }
+        if ($type eq 'c') {
+            $d .= "printf(\"arg$i:'%s' \", copyinstr(arg$i)); ";
+        }
+        $i++;
+    }
+    $d .= '}';
+
+    return $d;
+}
+         
+sub run_dtrace {
+    my ($func, $name, @types) = @_;
+    my $d = gen_d(@types);
+
+    my $test;
+    if (defined $arch) {
+        $test = "./test_usdt$arch $func $name " . (join ' ', @types);
+    }
+    else {
+        $test = "./test_usdt $func $name " . (join ' ', @types);
+    }
+
+    my @cmd = ('dtrace', '-Zn', $d, '-c', $test);
+
+    my ($wtr, $rdr, $err);
+    $err = gensym;
+    my $pid = open3($wtr, $rdr, $err, @cmd);
+
+    waitpid( $pid, 0 );
+    my $status = $? >> 8;
+
+    if ($status > 0) {
+        while (!$err->eof) {
+            print STDERR $err->getline;
+        }
+    }
+
+    my ($header, $output) = ($rdr->getline, $rdr->getline);
+    return ($status, $output || '');
+}

data/ext/libusdt/test_usdt.c

@@ -0,0 +1,60 @@
+#include "usdt.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+int main(int argc, char **argv) {
+        usdt_provider_t *provider;
+        usdt_probedef_t *probedef;
+        char *char_argv[6] = { "a", "b", "c", "d", "e", "f" };
+        int int_argv[6] = { 1, 2, 3, 4, 5, 6 };
+        void **args;
+        int i;
+
+        if (argc < 3) {
+                fprintf(stderr, "usage: %s func name [types ...]\n", argv[0]);
+                return(1);
+        }
+
+        if (argc > 3) {
+                args = malloc((argc-3) * sizeof(void *));
+        }
+
+        for (i = 0; i < 6; i++) {
+                if (argv[i+3] != NULL && i+3 < argc) {
+                        if (strncmp("c", argv[i+3], 1) == 0) {
+                                args[i] = (void *)char_argv[i];
+                                argv[i+3] = strdup("char *");
+                        }
+                        if (strncmp("i", argv[i+3], 1) == 0) {
+                                args[i] = (void *)(long)int_argv[i];
+                                argv[i+3] = strdup("int");
+                        }
+                }
+        }
+
+        if ((provider = usdt_create_provider("testlibusdt", "modname")) == NULL) {
+                fprintf(stderr, "unable to create provider\n");
+                exit (1);
+        }
+        if ((probedef = usdt_create_probe((const char *)argv[1],
+                                          (const char *)argv[2],
+                                          (argc-3), (const char **)&argv[3])) == NULL)
+        {
+                fprintf(stderr, "unable to create probe\n");
+                exit (1);
+        }
+        usdt_provider_add_probe(provider, probedef);
+
+        if ((usdt_provider_enable(provider)) < 0) {
+                fprintf(stderr, "unable to enable provider: %s\n", usdt_errstr(provider));
+                exit (1);
+        }
+
+        if (usdt_is_enabled(probedef->probe)) {
+                usdt_fire_probe(probedef->probe, (argc-3), (void **)args);
+        }
+
+        return 0;
+}

data/ext/libusdt/usdt.c

@@ -0,0 +1,198 @@
+#include "usdt_internal.h"
+
+#include <stdlib.h>
+#include <stdarg.h>
+
+char *usdt_errors[] = {
+  "failed to allocate memory",
+  "failed to allocate page-aligned memory",
+  "no probes defined",
+  "failed to load DOF"
+};
+
+usdt_provider_t *
+usdt_create_provider(const char *name, const char *module)
+{
+        usdt_provider_t *provider;
+
+        if ((provider = malloc(sizeof *provider)) == NULL) 
+                return NULL;
+
+        provider->name = strdup(name);
+        provider->module = strdup(module);
+        provider->probedefs = NULL;
+
+        return provider;
+}
+
+usdt_probedef_t *
+usdt_create_probe_varargs(const char *func, const char *name, ...)
+{
+        va_list ap;
+        int i;
+        const char *type;
+        usdt_probedef_t *p;
+
+        if ((p = malloc(sizeof *p)) == NULL)
+                return (NULL);
+
+        p->function = strdup(func);
+        p->name = strdup(name);
+
+        va_start(ap, name);
+
+        for (i = 0; i < 6; i++) {
+                if ((type = va_arg(ap, const char *)) != NULL) {
+                        if (strncmp("char *", type, 6)) {
+                                p->types[i] = USDT_ARGTYPE_STRING;
+                        }
+                        if (strncmp("int", type, 3)) {
+                                p->types[i] = USDT_ARGTYPE_INTEGER;
+                        }
+                }
+                else {
+                        p->types[i] = USDT_ARGTYPE_NONE;
+                }
+        }
+
+        return (p);
+}
+
+usdt_probedef_t *
+usdt_create_probe(const char *func, const char *name, size_t argc, const char **types)
+{
+        int i;
+        usdt_probedef_t *p;
+
+        if ((p = malloc(sizeof *p)) == NULL)
+                return (NULL);
+
+        p->function = strdup(func);
+        p->name = strdup(name);
+        p->argc = argc;
+
+        for (i = 0; i < 6; i++) {
+                if (i < argc && types[i] != NULL) {
+                        if (strncmp("char *", types[i], 6) == 0)
+                                p->types[i] = USDT_ARGTYPE_STRING;
+                        if (strncmp("int", types[i], 3) == 0)
+                                p->types[i] = USDT_ARGTYPE_INTEGER;
+                }
+                else {
+                        p->types[i] = USDT_ARGTYPE_NONE;
+                }
+        }
+
+        return (p);
+}
+
+void
+usdt_provider_add_probe(usdt_provider_t *provider, usdt_probedef_t *probedef)
+{
+        usdt_probedef_t *pd;
+
+        probedef->next = NULL;
+        if (provider->probedefs == NULL)
+                provider->probedefs = probedef;
+        else {
+                for (pd = provider->probedefs; (pd->next != NULL); pd = pd->next) ;
+                pd->next = probedef;
+        }
+}
+
+uint8_t
+usdt_probedef_argc(usdt_probedef_t *probedef)
+{
+        uint8_t args = 0;
+        uint8_t i;
+
+        for (i = 0; probedef->types[i] != USDT_ARGTYPE_NONE && i < 6; i++)
+                args++;
+
+        return args;
+}
+
+int
+usdt_provider_enable(usdt_provider_t *provider)
+{
+        usdt_strtab_t strtab;
+        usdt_dof_file_t *file;
+        usdt_probedef_t *pd;
+        int i;
+        size_t size;
+        usdt_dof_section_t sects[5];
+
+        if (provider->probedefs == NULL) {
+                usdt_error(provider, USDT_ERROR_NOPROBES);
+                return (-1);
+        }
+
+        for (pd = provider->probedefs; pd != NULL; pd = pd->next) {
+                if ((pd->probe = malloc(sizeof(*pd->probe))) == NULL) {
+                        usdt_error(provider, USDT_ERROR_MALLOC);
+                        return (-1);
+                }
+        }
+
+        if ((usdt_strtab_init(&strtab, 0)) < 0) {
+                usdt_error(provider, USDT_ERROR_MALLOC);
+                return (-1);
+        }
+
+        if ((usdt_strtab_add(&strtab, provider->name)) < 0) {
+                usdt_error(provider, USDT_ERROR_MALLOC);
+                return (-1);
+        }
+
+        if ((usdt_dof_probes_sect(&sects[0], provider, &strtab)) < 0)
+                return (-1);
+        if ((usdt_dof_prargs_sect(&sects[1], provider)) < 0)
+                return (-1);
+
+        size = usdt_provider_dof_size(provider, &strtab);
+        if ((file = usdt_dof_file_init(provider, size)) == NULL)
+                return (-1);
+
+        if ((usdt_dof_proffs_sect(&sects[2], provider, file->dof)) < 0)
+                return (-1);
+        if ((usdt_dof_prenoffs_sect(&sects[3], provider, file->dof)) < 0)
+                return (-1);
+        if ((usdt_dof_provider_sect(&sects[4], provider)) < 0)
+                return (-1);
+
+        for (i = 0; i < 5; i++)
+                usdt_dof_file_append_section(file, &sects[i]);
+
+        usdt_dof_file_generate(file, &strtab);
+
+        if ((usdt_dof_file_load(file, provider->module)) < 0) {
+                usdt_error(provider, USDT_ERROR_LOADDOF);
+                return (-1);
+        }
+
+        return (0);
+}
+
+int
+usdt_is_enabled(usdt_probe_t *probe)
+{
+        return (*probe->isenabled_addr)();
+}
+
+void
+usdt_fire_probe(usdt_probe_t *probe, size_t argc, void **nargv)
+{
+        usdt_probe_args(probe->probe_addr, argc, nargv);
+}
+
+void
+usdt_error(usdt_provider_t *provider, usdt_error_t error)
+{
+        provider->error = usdt_errors[error];
+}
+
+char *
+usdt_errstr(usdt_provider_t *provider)
+{
+        return (provider->error);
+}

data/ext/libusdt/usdt.h

@@ -0,0 +1,50 @@
+#include <stdint.h>
+#include <unistd.h>
+
+typedef uint8_t usdt_argtype_t;
+#define USDT_ARGTYPE_NONE    0
+#define USDT_ARGTYPE_STRING  1
+#define USDT_ARGTYPE_INTEGER 2
+
+typedef enum usdt_error {
+        USDT_ERROR_MALLOC = 0,
+        USDT_ERROR_VALLOC,
+        USDT_ERROR_NOPROBES,
+        USDT_ERROR_LOADDOF
+} usdt_error_t;
+
+typedef struct usdt_probe {
+        int (*isenabled_addr)(void);
+        void *probe_addr;
+} usdt_probe_t;
+
+int usdt_is_enabled(usdt_probe_t *probe);
+void usdt_fire_probe(usdt_probe_t *probe, size_t argc, void **argv);
+
+typedef struct usdt_probedef {
+        const char *name;
+        const char *function;
+        size_t argc;
+        usdt_argtype_t types[6];
+        struct usdt_probe *probe;
+        struct usdt_probedef *next;
+} usdt_probedef_t;
+
+usdt_probedef_t *usdt_create_probe_varargs(const char *func, const char *name, ...);
+usdt_probedef_t *usdt_create_probe(const char *func, const char *name,
+                                   size_t argc, const char **types);
+
+typedef struct usdt_provider {
+        const char *name;
+        const char *module;
+        usdt_probedef_t *probedefs;
+        char *error;
+} usdt_provider_t;
+
+usdt_provider_t *usdt_create_provider(const char *name, const char *module);
+void usdt_provider_add_probe(usdt_provider_t *provider, usdt_probedef_t *probedef);
+int usdt_provider_enable(usdt_provider_t *provider);
+
+void usdt_error(usdt_provider_t *provider, usdt_error_t error);
+char *usdt_errstr(usdt_provider_t *provider);
+