gvl-tracing 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be2bff3cbad042f549ffee919cb659fe201d49714ae64924ae3fa30aba79d331
-  data.tar.gz: d138181409369aed6507b63efa33da6d4ccc261c7e0aae469fe250bcb2b062ae
+  metadata.gz: 1adc64642ec1cb371df66afa9f928cafe106349f981a3b8ec643232a0618b769
+  data.tar.gz: 9b250c7a07df1f9a1f907100554fa74eba043edb639ad1cc777b33ba705d98f3
 SHA512:
-  metadata.gz: 544ada893bf0c5b3152bd36a2a8fe6496b0609910d5b4e75044ea00c7c15acab999bc5708e8efff46f4b7022621108237bc700990d54c67c9a206401ce18cb56
-  data.tar.gz: 61de24e198a80220fe2d408aaa267b515032ddda686452501c445dd1a6af754c7fded4bb43ca9ba25091bcc6493e63b547d543bd2f0b5af5bfaf2fe1ca2dd755
+  metadata.gz: 5016d9734e5eeef9578fc83211bb68cbc26f68f1b93b41c3ff0fbd9f5a3b93745cb7de23c69cc228a903b17db565ee369ec3d41f7d9575e3107a04a9bf6368a0
+  data.tar.gz: 821d89427465c6496e09a773a1277d35388d4205fd5e0e5f054fd8da8d1a46d902e4f464764a0e5891bb9ebb63451295ea2bf1986c085616b2ff60926dcbde7a

data/README.adoc

@@ -8,7 +8,7 @@ A Ruby gem for getting a timeline view of Global VM Lock usage in your Ruby app
 
 image::preview.png[]
 
-See my blog post **FIXME** for more details!
+See my blog post https://ivoanjo.me/blog/2022/07/17/tracing-ruby-global-vm-lock/[tracing ruby's (global) vm lock] for more details!
 
 NOTE: This gem only works on Ruby 3.2 and above because it depends on the new https://github.com/ruby/ruby/pull/5500[GVL Instrumentation API]. See below for an easy way to run Ruby 3.2 inside docker.
 
@@ -45,7 +45,23 @@ To do so:
 
 == Quick start using docker
 
-**FIXME: TODO**
+The `gvl-tracing` gem requires Ruby 3.2, which is still under development. If you have docker installed on your machine, you can use the https://hub.docker.com/r/rubylang/ruby[ruby-lang development images] to try it out.
+
+Here's how you can use them:
+
+[source,bash]
+----
+$ cd my_ruby_app/
+$ docker run -v $(pwd):/app -it rubylang/ruby:master-focal
+root@0e0b07edf906:/# cd app/
+root@0e0b07edf906:/app# ruby -v
+ruby 3.2.0dev (2022-07-23T12:42:05Z master 721d154e2f) [x86_64-linux]
+root@0e0b07edf906:/app# gem install gvl-tracing
+Building native extensions. This could take a while...
+Successfully installed gvl-tracing-0.1.1
+1 gem installed
+root@0e0b07edf906:/app# ruby <your app>
+----
 
 == Installation
 

data/examples/example2.rb

@@ -0,0 +1,14 @@
+require "gvl-tracing"
+
+def fib(n)
+  return n if n <= 1
+  fib(n - 1) + fib(n - 2)
+end
+
+GvlTracing.start("example2.json")
+
+other_thread = Thread.new { fib(37) } # runs in other thread
+fib(37) # runs in main thread
+
+other_thread.join
+GvlTracing.stop

data/examples/example3.rb

@@ -0,0 +1,14 @@
+require "gvl-tracing"
+
+def fib(n)
+  return n if n <= 1
+  fib(n - 1) + fib(n - 2)
+end
+
+GvlTracing.start("example3.json")
+
+other_ractor = Ractor.new { fib(37) } # runs in other ractor
+fib(37) # runs in main thread
+
+other_ractor.take
+GvlTracing.stop

data/examples/gc.rb

@@ -0,0 +1,13 @@
+require "gvl-tracing"
+
+def alloc(n)
+  n.times { Object.new }
+end
+
+GvlTracing.start("gc.json")
+
+3.times.map { Thread.new { alloc(100_000) } }.map(&:join)
+
+sleep(0.05)
+
+GvlTracing.stop

data/ext/gvl_tracing_native_extension/gvl_tracing.c

@@ -24,31 +24,49 @@
 // SOFTWARE.
 
 #include <ruby/ruby.h>
+#include <ruby/debug.h>
 #include <ruby/thread.h>
+#include <ruby/atomic.h>
 #include <errno.h>
 #include <stdbool.h>
 #include <sys/types.h>
-#include <unistd.h>
 
 static VALUE tracing_start(VALUE _self, VALUE output_path);
 static VALUE tracing_stop(VALUE _self);
 static double timestamp_microseconds(void);
 static void render_event(const char *event_name);
-static void on_event(rb_event_flag_t event, const rb_internal_thread_event_data_t *_unused1, void *_unused2);
+static void on_thread_event(rb_event_flag_t event, const rb_internal_thread_event_data_t *_unused1, void *_unused2);
+static void on_gc_event(VALUE tpval, void *_unused1);
+
+// Thread-local state
+static _Thread_local bool current_thread_serial_set = false;
+static _Thread_local unsigned int current_thread_serial = 0;
 
 // Global mutable state
+static rb_atomic_t thread_serial = 0;
 static FILE *output_file = NULL;
 static rb_internal_thread_event_hook_t *current_hook = NULL;
 static double started_tracing_at_microseconds = 0;
 static pid_t process_id = 0;
+static VALUE gc_tracepoint = Qnil;
 
 void Init_gvl_tracing_native_extension(void) {
+  rb_global_variable(&gc_tracepoint);
+
   VALUE gvl_tracing_module = rb_define_module("GvlTracing");
 
   rb_define_singleton_method(gvl_tracing_module, "start", tracing_start, 1);
   rb_define_singleton_method(gvl_tracing_module, "stop", tracing_stop, 0);
 }
 
+static inline unsigned int current_thread_id(void) {
+    if (!current_thread_serial_set) {
+        current_thread_serial_set = true;
+        current_thread_serial = RUBY_ATOMIC_FETCH_ADD(thread_serial, 1);
+    }
+    return (unsigned int)current_thread_serial;
+}
+
 static VALUE tracing_start(VALUE _self, VALUE output_path) {
   Check_Type(output_path, T_STRING);
 
@@ -63,7 +81,7 @@ static VALUE tracing_start(VALUE _self, VALUE output_path) {
   render_event("started_tracing");
 
   current_hook = rb_internal_thread_add_event_hook(
-    on_event,
+    on_thread_event,
     (
       RUBY_INTERNAL_THREAD_EVENT_READY |
       RUBY_INTERNAL_THREAD_EVENT_RESUMED |
@@ -74,6 +92,17 @@ static VALUE tracing_start(VALUE _self, VALUE output_path) {
     NULL
   );
 
+  gc_tracepoint = rb_tracepoint_new(
+    0,
+    (
+      RUBY_INTERNAL_EVENT_GC_ENTER |
+      RUBY_INTERNAL_EVENT_GC_EXIT
+    ),
+    on_gc_event,
+    (void *) NULL
+  );
+  rb_tracepoint_enable(gc_tracepoint);
+
   return Qtrue;
 }
 
@@ -81,6 +110,8 @@ static VALUE tracing_stop(VALUE _self) {
   if (output_file == NULL) rb_raise(rb_eRuntimeError, "Tracing not running");
 
   rb_internal_thread_remove_event_hook(current_hook);
+  rb_tracepoint_disable(gc_tracepoint);
+  gc_tracepoint = Qnil;
 
   render_event("stopped_tracing");
   fprintf(output_file, "]\n");
@@ -103,11 +134,14 @@ static double timestamp_microseconds(void) {
 static void render_event(const char *event_name) {
   // Event data
   double now_microseconds = timestamp_microseconds() - started_tracing_at_microseconds;
-  pid_t thread_id = gettid();
+  unsigned int thread_id = current_thread_id();
 
   // Each event is converted into two events in the output: one that signals the end of the previous event
   // (whatever it was), and one that signals the start of the actual event we're processing.
-  // Yes this is seems to be bending a bit the intention of the output format, but it seemed easier to do this way.
+  // Yes, this seems to be slightly bending the intention of the output format, but it seemed easier to do this way.
+
+  // Important note: We've observed some rendering issues in perfetto if the tid or pid are numbers that are "too big",
+  // see https://github.com/ivoanjo/gvl-tracing/pull/4#issuecomment-1196463364 for an example.
 
   fprintf(output_file,
     // Finish previous duration
@@ -121,14 +155,24 @@ static void render_event(const char *event_name) {
   );
 }
 
-static void on_event(rb_event_flag_t event_id, const rb_internal_thread_event_data_t *_unused1, void *_unused2) {
+static void on_thread_event(rb_event_flag_t event_id, const rb_internal_thread_event_data_t *_unused1, void *_unused2) {
   const char* event_name = "bug_unknown_event";
   switch (event_id) {
     case RUBY_INTERNAL_THREAD_EVENT_READY:     event_name = "ready";     break;
-    case RUBY_INTERNAL_THREAD_EVENT_RESUMED:   event_name = "resumed";   break;
-    case RUBY_INTERNAL_THREAD_EVENT_SUSPENDED: event_name = "suspended"; break;
+    case RUBY_INTERNAL_THREAD_EVENT_RESUMED:   event_name = "running";   break;
+    case RUBY_INTERNAL_THREAD_EVENT_SUSPENDED: event_name = "waiting";   break;
     case RUBY_INTERNAL_THREAD_EVENT_STARTED:   event_name = "started";   break;
     case RUBY_INTERNAL_THREAD_EVENT_EXITED:    event_name = "exited";    break;
   };
   render_event(event_name);
 }
+
+static void on_gc_event(VALUE tpval, void *_unused1) {
+  const char* event_name = "bug_unknown_event";
+  switch (rb_tracearg_event_flag(rb_tracearg_from_tracepoint(tpval))) {
+    case RUBY_INTERNAL_EVENT_GC_ENTER: event_name = "gc"; break;
+    // TODO: is it possible the thread wasn't running? Might need to save the last state.
+    case RUBY_INTERNAL_EVENT_GC_EXIT: event_name = "running"; break;
+  }
+  render_event(event_name);
+}

data/lib/gvl_tracing/version.rb

@@ -26,5 +26,5 @@
 # frozen_string_literal: true
 
 module GvlTracing
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gvl-tracing
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Ivo Anjo
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-07-24 00:00:00.000000000 Z
+date: 2022-07-27 00:00:00.000000000 Z
 dependencies: []
 description: 
 email:
@@ -26,6 +26,12 @@ files:
 - Rakefile
 - examples/example1.json.gz
 - examples/example1.rb
+- examples/example2.json.gz
+- examples/example2.rb
+- examples/example3.json.gz
+- examples/example3.rb
+- examples/gc.json.gz
+- examples/gc.rb
 - ext/gvl_tracing_native_extension/extconf.rb
 - ext/gvl_tracing_native_extension/gvl_tracing.c
 - gems.rb