exec_trace 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cbb1b6cf45d5283b3c16f4084bfaca1578453758f34e5fbfc178a4d4b6ce0abb
+  data.tar.gz: 2b66700283869ccf821b851b4e00d1c76043789e50a9d73de9f7698bfa05a417
+SHA512:
+  metadata.gz: ec2102be13afe2de8409f89348b5e4d032344315a1ecb996c19de5e75873f16f2994abd9e2e2e6e6e3f2a1970923f2c90a26dfe6aa82a8210f844c9de36a8bf7
+  data.tar.gz: c72678f58fa819a54d92660e756cc108fa7255f3dbf4d297cd9a45fe4710b03e69a95c7faae9b4936fdec07b48b4c8c60364f9f798f3b9987e4d56fdc8dffba6

data/.github/workflows/main.yml

@@ -0,0 +1,19 @@
+name: Ruby
+
+on: [push,pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 2.7.1
+    - name: Run the default task
+      run: |
+        gem install bundler -v 2.2.9
+        bundle install
+        bundle exec rake compile
+        bundle exec rake

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+ext/Makefile
+ext/extconf.h
+ext/mkmf.log
+lib

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in exec_trace.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "minitest", "~> 5.0"

data/Gemfile.lock

@@ -0,0 +1,24 @@
+PATH
+  remote: .
+  specs:
+    exec_trace (0.0.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    minitest (5.14.3)
+    rake (13.0.3)
+    rake-compiler (1.1.1)
+      rake
+
+PLATFORMS
+  x86_64-darwin-19
+
+DEPENDENCIES
+  exec_trace!
+  minitest (~> 5.0)
+  rake (~> 13.0)
+  rake-compiler (~> 1.1)
+
+BUNDLED WITH
+   2.2.9

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Blake Williams
+
+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,49 @@
+# ExecTrace
+
+Trace Ruby code, returning methods that were run, how many times they were
+called, how long they took to run, and the methods they called.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'exec_trace'
+```
+
+## Usage
+
+```ruby
+require "pp"
+require "exec_trace"
+
+result = exec_trace do
+  u = User.new
+  u.save!
+end
+
+pp result
+```
+
+`exec_trace` returns an array of arrays. Each top-level array is a top-level call in the
+`exec_trace` block. Frame consist 4 fields: file name + line number,
+calls, time in microseconds, and an array of frames that it called.
+
+e.g.
+
+```
+[
+  ["/Users/me/exec_trace/test/exec_trace_test.rb:23", 1, 52, [
+    ["/Users/me/exec_trace/test/exec_trace_test.rb:24", 5, 2518388, []]
+  ]]
+]
+```
+
+## Developing
+
+* To compile the C extension: `bundle exec rake compile`
+* To run the tests `bundle exec rake test`
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test
+
+# Extension
+require "rake/extensiontask"
+
+Rake::ExtensionTask.new("exec_trace") do |e|
+  e.ext_dir = "ext"
+end

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "exec_trace"
+
+# 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/exec_trace.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name          = "exec_trace"
+  spec.version       = "0.0.1"
+  spec.authors       = ["Blake Williams"]
+  spec.email         = ["blake@blakewilliams.me"]
+
+  spec.summary       = "Trace your Ruby function's execution path"
+  spec.description   = spec.summary
+  spec.homepage      = "https://github.com/blakewilliams/exec_trace"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.4.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.extensions = ["ext/extconf.rb"]
+
+  spec.add_development_dependency "rake-compiler", "~> 1.1"
+end

data/ext/exec_trace.c

@@ -0,0 +1,267 @@
+#include <ruby.h>
+#include <stdio.h>
+
+#include <sys/time.h>
+#include <time.h>
+
+#include <ruby/debug.h>
+#include <ruby/intern.h>
+
+typedef uint64_t usec_t;
+
+static usec_t
+wall_usec()
+{
+  struct timeval tv;
+  gettimeofday(&tv, NULL);
+
+  // Convert timestamp to us
+  return (usec_t)tv.tv_sec * 1000000 + (usec_t)tv.tv_usec;
+}
+
+typedef struct frame
+{
+  rb_event_flag_t event;
+  char* file_name;
+  int line_number;
+  int calls;
+
+  struct frame* parent;
+
+  int subframe_count;
+  int subframe_size;
+  struct frame** subframes;
+
+  usec_t wall_total_usec;
+  usec_t wall_start_usec;
+  usec_t wall_children_usec;
+} frame_t;
+
+static struct
+{
+  uint64_t top_frame_used;
+  frame_t* top_frames[65536];
+  frame_t* last_frame;
+  VALUE thread;
+} tracer = {};
+
+static void
+trace_hook(rb_event_flag_t event, VALUE data, VALUE self, ID mid, VALUE klass)
+{
+  // Ignore other threads
+  if (tracer.thread != rb_thread_current()) {
+    return;
+  }
+
+  int buff_size = 2;
+  VALUE buff[buff_size];
+  int lines[buff_size];
+  // https://github.com/ruby/ruby/blob/48b94b791997881929c739c64f95ac30f3fd0bb9/include/ruby/debug.h
+  // start 0, limit to 2 frames, buff = iseqs, lines == line numbers
+  int collected_size = rb_profile_frames(0, buff_size, buff, lines);
+
+  if (collected_size == 0) {
+    return;
+  }
+
+  int line_index = 0;
+
+  if (!mid && collected_size == 2) {
+    line_index = 1;
+  }
+
+  VALUE path = rb_profile_frame_absolute_path(buff[line_index]);
+
+  if (NIL_P(path)) {
+    line_index = 0;
+    path = rb_profile_frame_absolute_path(buff[line_index]);
+    if (NIL_P(path)) {
+      return;
+    }
+  }
+  char* file = StringValueCStr(path);
+  int line = lines[line_index];
+
+  if (!file || line <= 0) {
+    return;
+  }
+
+  frame_t* frame;
+  frame_t* last_top_frame = tracer.top_frames[tracer.top_frame_used - 1];
+
+  switch (event) {
+    case RUBY_EVENT_CALL:
+    case RUBY_EVENT_C_CALL:
+      if (tracer.last_frame && tracer.last_frame->file_name == file &&
+          tracer.last_frame->line_number == line) {
+        // collapse duplicate frames
+        return;
+      } else if (last_top_frame && last_top_frame->file_name == file &&
+                 last_top_frame->line_number == line) {
+        // collapse duplicate top-level frames
+        return;
+      } else {
+        if (tracer.last_frame) {
+          for (int i = 0; i < tracer.last_frame->subframe_count; i++) {
+            frame = tracer.last_frame->subframes[i];
+
+            if (frame->file_name == file && frame->line_number == line) {
+              frame->calls++;
+              frame->wall_start_usec = wall_usec();
+              tracer.last_frame = frame;
+              return;
+            }
+          }
+        }
+
+        frame = malloc(sizeof(frame_t));
+
+        frame->event = event;
+        frame->file_name = file;
+        frame->line_number = line;
+        frame->calls = 1;
+        frame->subframe_count = 0;
+        frame->subframe_size = 1;
+        frame->subframes = malloc(1 * sizeof(frame_t*));
+        frame->wall_start_usec = wall_usec();
+        frame->wall_total_usec = 0;
+        frame->wall_children_usec = 0;
+        frame->parent = tracer.last_frame;
+
+        if (tracer.last_frame) {
+          frame_t* last_frame = tracer.last_frame;
+          if (last_frame->subframe_size == last_frame->subframe_count) {
+            last_frame->subframe_size *= 2;
+            tracer.last_frame->subframes =
+              realloc(tracer.last_frame->subframes,
+                      sizeof(frame_t*) * last_frame->subframe_size);
+          }
+
+          last_frame->subframe_count++;
+          last_frame->subframes[last_frame->subframe_count - 1] = frame;
+        } else {
+          tracer.top_frame_used++;
+          tracer.top_frames[tracer.top_frame_used - 1] = frame;
+        }
+      }
+
+      tracer.last_frame = frame;
+      break;
+    case RUBY_EVENT_RETURN:
+    case RUBY_EVENT_C_RETURN: {
+      frame_t* current_frame = tracer.last_frame;
+      while (1) {
+        if (current_frame && current_frame->file_name == file &&
+            current_frame->line_number == line) {
+          usec_t time = wall_usec() - tracer.last_frame->wall_start_usec;
+          if (tracer.last_frame->parent) {
+            tracer.last_frame->parent->wall_children_usec += time;
+          }
+          tracer.last_frame->wall_total_usec += time;
+          tracer.last_frame = current_frame->parent;
+          return;
+        } else if (current_frame) {
+          current_frame = current_frame->parent;
+        } else {
+          return;
+        }
+      }
+    }
+  }
+}
+
+/*
+  Ensure trace is cleaned up by removing the event hook.
+*/
+static VALUE
+exec_trace_ensure(VALUE self)
+{
+  rb_remove_event_hook((rb_event_hook_func_t)trace_hook);
+
+  return self;
+}
+
+static void
+create_frame_array(VALUE arr, frame_t* frame)
+{
+  VALUE fname = rb_sprintf("%s:%i", frame->file_name, frame->line_number);
+  rb_ary_push(arr, fname);
+  rb_ary_push(arr, INT2FIX(frame->calls));
+  rb_ary_push(arr, INT2FIX(frame->wall_total_usec - frame->wall_children_usec));
+
+  VALUE subframe_ary = rb_ary_new();
+
+  if (frame->subframe_count == 0) {
+    rb_ary_push(arr, subframe_ary);
+    return;
+  }
+
+  for (int i = 0; i < frame->subframe_count; i++) {
+    VALUE frame_ary = rb_ary_new();
+    create_frame_array(frame_ary, frame->subframes[i]);
+    rb_ary_push(subframe_ary, frame_ary);
+  }
+
+  rb_ary_push(arr, subframe_ary);
+}
+
+static void
+cleanup(frame_t* frame)
+{
+  if (frame->subframe_count > 0) {
+    for (int i = 0; i < frame->subframe_count; i++) {
+      cleanup(frame->subframes[i]);
+    }
+  }
+
+  free(frame->subframes);
+  free(frame);
+}
+
+/*
+  Global function that begins tracing
+*/
+VALUE
+exec_trace(VALUE self)
+{
+  // Capture current thread ID to ensure we don't capture frames from other
+  // threads.
+  tracer.thread = rb_thread_current();
+
+  // Start listening for call events
+  rb_add_event_hook((rb_event_hook_func_t)trace_hook,
+                    RUBY_EVENT_CALL | RUBY_EVENT_C_CALL | RUBY_EVENT_RETURN |
+                      RUBY_EVENT_C_RETURN,
+                    Qnil);
+
+  // Call passed in block, ensure trace hook is removed
+  rb_ensure(rb_yield, Qnil, exec_trace_ensure, self);
+
+  VALUE top_level_frame_ary = rb_ary_new();
+
+  for (uint64_t i = 0; i < tracer.top_frame_used; i++) {
+    VALUE frame_ary = rb_ary_new();
+    create_frame_array(frame_ary, tracer.top_frames[i]);
+    rb_ary_push(top_level_frame_ary, frame_ary);
+
+    // Cleanup malloc'd memory
+    cleanup(tracer.top_frames[i]);
+  }
+
+  // Cleanup for another run
+  tracer.top_frame_used = 0;
+  tracer.last_frame = NULL;
+  memset(tracer.top_frames, 0, sizeof(tracer.top_frames));
+
+  return top_level_frame_ary;
+}
+
+/*
+   Entrypoint for a gem extension and defines the global
+   `exec_trace` function.
+*/
+void
+Init_exec_trace(void)
+{
+  rb_define_global_function("exec_trace", exec_trace, 0);
+}

data/ext/extconf.rb

@@ -0,0 +1,8 @@
+require 'mkmf'
+
+have_header "ruby/intern.h"
+have_header "ruby/debug.h"
+have_func('rb_profile_frames')
+have_func('rb_thread_current')
+
+create_makefile "exec_trace"

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: exec_trace
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Blake Williams
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2021-02-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+description: Trace your Ruby function's execution path
+email:
+- blake@blakewilliams.me
+executables: []
+extensions:
+- ext/extconf.rb
+extra_rdoc_files: []
+files:
+- ".github/workflows/main.yml"
+- ".gitignore"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- exec_trace.gemspec
+- ext/exec_trace.c
+- ext/extconf.rb
+homepage: https://github.com/blakewilliams/exec_trace
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/blakewilliams/exec_trace
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: Trace your Ruby function's execution path
+test_files: []