usdt_marker 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a52c971244aa67756a460f5696813fc3e7dc6cf9aa6339512b36a1028989a97d
+  data.tar.gz: 6181803757c4dd53d4bece09ecf013ea49f436106151421df89600b6053a7b39
+SHA512:
+  metadata.gz: d5beafc4f4224cfc7fb96e546ba66840a675e0645501da6d4f5f52705d05fb7b666bf6451f1eac797e03c3fbf08bfb8f0af3483975802c31db16f840b9f02bf4
+  data.tar.gz: 5883823bb5a7b283b348f927474c90d7f43d3a69650e8b7b15298fc6cfee4d842195dd72e151457e88da704bb6adaf4ae30107d4257a83556a593c15ebb944fe

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in usdt_marker.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+gem "rake-compiler"

data/Gemfile.lock

@@ -0,0 +1,23 @@
+PATH
+  remote: .
+  specs:
+    usdt_marker (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    rake (13.0.1)
+    rake-compiler (1.1.0)
+      rake
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (>= 1.6)
+  rake (~> 13.0)
+  rake-compiler
+  usdt_marker!
+
+BUNDLED WITH
+   2.0.2

data/README.md

@@ -0,0 +1,118 @@
+# UsdtMarker
+
+(BADGE)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'usdt_marker'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install usdt_marker
+
+### Limitations
+
+* This is tested only against Linux system; My environment uses kernel 5.0.0 :)
+  * Extention requires a package named `systemtap-sdt-dev` or something alike
+* I know some of UNIX systems also has `<sys/sdt.h>` header file, but I'm not going to test.
+  * Your supports are welcomed!
+
+## Usage
+
+Very simple tutorial.
+
+Install those tools to your system:
+
+* package `systemtap-sdt-dev` or something alike.
+* `bpftrace`. We recommend via OS package, binary or self-build, because snap version of bpftrace cannot recognize uprobe/usdt for now.
+* Ruby. Some systems may require `ruby-dev` package.
+
+Then invoke your irb, e.g. in the bundle environment with usdt_marker.
+
+```ruby
+irb(main):001:0> require 'usdt_marker'
+irb(main):002:0> puts $$
+19644
+```
+
+On onother terminal, hit `bpftrace` to find the name of USDT; USDT may be defined in gem's shared object:
+
+```console
+$ sudo bpftrace -p 19644 -l 'usdt:*' | grep ruby
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:array__create
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:raise
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:gc__sweep__end
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:gc__sweep__begin
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:gc__mark__end
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:gc__mark__begin
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:hash__create
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:load__entry
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:load__return
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:find__require__return
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:require__entry
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:find__require__entry
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:require__return
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:object__create
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:parse__begin
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:parse__end
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:string__create
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:symbol__create
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:method__cache__clear
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:cmethod__entry
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:cmethod__return
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:method__return
+usdt:/root/.rbenv/versions/2.6.5/lib/libruby.so.2.6.5:ruby:method__entry
+usdt:/usr/local/ghq/github.com/udzura/usdt_marker/lib/usdt_marker/usdt_marker.so:rubygem:usdt_marker_i1s1
+usdt:/usr/local/ghq/github.com/udzura/usdt_marker/lib/usdt_marker/usdt_marker.so:rubygem:usdt_marker_i2
+```
+
+Then start tracing:
+
+```
+$ sudo bpftrace -p 19644 -e \
+  'usdt:/usr/local/ghq/github.com/udzura/usdt_marker/lib/usdt_marker/usdt_marker.so:rubygem:usdt_marker_i1s1 {
+    printf("Fire!: %d, %s\n", arg0, str(arg1));
+  }'
+Attaching 1 probe...
+```
+
+Return to irb, hit probe methods:
+
+```ruby
+irb(main):003:0> UsdtMarker.probe_i1s1(2020, "hello, world!")
+=> true
+irb(main):004:0> UsdtMarker.probe_i1s1(2020, "hello, world! again")
+=> true
+```
+
+After all bpftrace process traces these events:
+
+```
+...
+Fire!: 2020, hello, world!
+Fire!: 2020, hello, world! again
+```
+
+Method-USDT counterparts:
+
+* `UsdtMarker.probe_i1s1(<Integer>, <String>)` - `rubygem:usdt_marker_i1s1`
+* `UsdtMarker.probe_i2(<Integer>, <Integer>)` - `rubygem:usdt_marker_i2`
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/udzura/usdt_marker.
+

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/extensiontask"
+
+task :build => :compile
+
+Rake::ExtensionTask.new("usdt_marker") do |ext|
+  ext.lib_dir = "lib/usdt_marker"
+end
+
+task :default => [:clobber, :compile, :spec]

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "usdt_marker"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/ext/usdt_marker/extconf.rb

@@ -0,0 +1,5 @@
+require "mkmf"
+
+abort "missing <sys/sdt.h>. Please install systemtap-sdt-dev or something like that" unless have_header("sys/sdt.h")
+
+create_makefile("usdt_marker/usdt_marker")

data/ext/usdt_marker/usdt_marker.c

@@ -0,0 +1,39 @@
+#include <sys/sdt.h>
+#include "usdt_marker.h"
+
+VALUE rb_mUsdtMarker;
+
+#ifndef __APPLE__
+static VALUE
+rb_probe_i2 (VALUE mod, VALUE arg0, VALUE arg1) {
+  DTRACE_PROBE2(rubygem, usdt_marker_i2, NUM2LONG(arg0), NUM2LONG(arg1));
+  return Qtrue;
+}
+
+static VALUE
+rb_probe_i1s1 (VALUE mod, VALUE arg0, VALUE arg1) {
+  DTRACE_PROBE2(rubygem, usdt_marker_i1s1, NUM2LONG(arg0), StringValuePtr(arg1));
+  return Qtrue;
+}
+#else
+#include <err.h>
+static VALUE
+rb_probe_i2 (VALUE mod, VALUE arg0, VALUE arg1) {
+  warn("MacOS is never supported, because they would not have DTRACE_PROBE*\n");
+  return Qtrue;
+}
+
+static VALUE
+rb_probe_i1s1 (VALUE mod, VALUE arg0, VALUE arg1) {
+  warn("MacOS is never supported, because they would not have DTRACE_PROBE*\n");
+  return Qtrue;
+}
+#endif
+
+void
+Init_usdt_marker(void)
+{
+  rb_mUsdtMarker = rb_define_module("UsdtMarker");
+  rb_define_module_function(rb_mUsdtMarker, "probe_i2", rb_probe_i2, 2);
+  rb_define_module_function(rb_mUsdtMarker, "probe_i1s1", rb_probe_i1s1, 2);
+}

data/ext/usdt_marker/usdt_marker.h

@@ -0,0 +1,6 @@
+#ifndef USDT_MARKER_H
+#define USDT_MARKER_H 1
+
+#include "ruby.h"
+
+#endif /* USDT_MARKER_H */

data/lib/usdt_marker.rb

@@ -0,0 +1,7 @@
+require "usdt_marker/version"
+require "usdt_marker/usdt_marker"
+
+module UsdtMarker
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/lib/usdt_marker/version.rb

@@ -0,0 +1,3 @@
+module UsdtMarker
+  VERSION = "0.1.0"
+end

data/usdt_marker.gemspec

@@ -0,0 +1,23 @@
+require_relative 'lib/usdt_marker/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "usdt_marker"
+  spec.version       = UsdtMarker::VERSION
+  spec.authors       = ["Uchio Kondo"]
+  spec.email         = ["udzura@udzura.jp"]
+
+  spec.summary       = %q{Event marker using USDT}
+  spec.description   = %q{Event marker using USDT. You can trace those user-defined events from eBPF.}
+  spec.homepage      = "https://github.com/udzura/usdt_marker"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+  spec.extensions    = ["ext/usdt_marker/extconf.rb"]
+
+  spec.add_development_dependency "bundler", ">= 1.6"
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: usdt_marker
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Uchio Kondo
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2020-03-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+description: Event marker using USDT. You can trace those user-defined events from
+  eBPF.
+email:
+- udzura@udzura.jp
+executables: []
+extensions:
+- ext/usdt_marker/extconf.rb
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- ext/usdt_marker/extconf.rb
+- ext/usdt_marker/usdt_marker.c
+- ext/usdt_marker/usdt_marker.h
+- lib/usdt_marker.rb
+- lib/usdt_marker/version.rb
+- usdt_marker.gemspec
+homepage: https://github.com/udzura/usdt_marker
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.6
+signing_key: 
+specification_version: 4
+summary: Event marker using USDT
+test_files: []