gvl-tracing 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be2bff3cbad042f549ffee919cb659fe201d49714ae64924ae3fa30aba79d331
-  data.tar.gz: d138181409369aed6507b63efa33da6d4ccc261c7e0aae469fe250bcb2b062ae
+  metadata.gz: 64d9b437af5f15e4a865a580486df67974e42b22b9836fa37e4de608597bf8d8
+  data.tar.gz: 52e7ecb9f89e613acd619a4225cfa2ac1f83cbf42e9173d59ccb91db09a1e7c6
 SHA512:
-  metadata.gz: 544ada893bf0c5b3152bd36a2a8fe6496b0609910d5b4e75044ea00c7c15acab999bc5708e8efff46f4b7022621108237bc700990d54c67c9a206401ce18cb56
-  data.tar.gz: 61de24e198a80220fe2d408aaa267b515032ddda686452501c445dd1a6af754c7fded4bb43ca9ba25091bcc6493e63b547d543bd2f0b5af5bfaf2fe1ca2dd755
+  metadata.gz: 529be0892156b7060427359d3e4386ed4f2bf0d96a3671896a6fcde4d347370e061567b8f88718ec894520ff9dc4b3bc667810da6d16b3ed171ef004ea3ecaf3
+  data.tar.gz: 8702d542f6962be8f0b471ed15e66c6ff4da1a41eadd121edacb3ade280109eeb219b4b7a6c1786ba13518948406f5182102af1fc363c7327e9a3c5bfe5e2cd4

data/README.adoc

@@ -8,9 +8,9 @@ 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.
+NOTE: This gem only works on Ruby 3.2 and above because it depends on the https://github.com/ruby/ruby/pull/5500[GVL Instrumentation API].
 
 == Quickest start
 
@@ -43,10 +43,6 @@ To do so:
 1. Download link:https://github.com/ivoanjo/gvl-tracing/blob/master/examples/example1.json.gz?raw=true[`examples/example1.json.gz`]
 2. Navigate to https://ui.perfetto.dev/ and use the **Open trace file** option to load the file
 
-== Quick start using docker
-
-**FIXME: TODO**
-
 == Installation
 
 Install the gem and add to the application's `Gemfile` or `gems.rb` file by executing:

data/ext/gvl_tracing_native_extension/extconf.rb

@@ -32,4 +32,10 @@ end
 
 require "mkmf"
 
+have_func("gettid", "unistd.h")
+have_header("pthread.h")
+have_func("pthread_getname_np", "pthread.h")
+have_func("pthread_threadid_np", "pthread.h")
+
+create_header
 create_makefile "gvl_tracing_native_extension"

data/ext/gvl_tracing_native_extension/gvl_tracing.c

@@ -24,31 +24,78 @@
 // 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>
+
+#include "extconf.h"
+
+#ifdef HAVE_PTHREAD_H
+  #include <pthread.h>
+#endif
+
+#ifdef HAVE_GETTID
+  #include <unistd.h>
+#endif
 
 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 void initialize_thread_id(void) {
+  current_thread_serial_set = true;
+  current_thread_serial = RUBY_ATOMIC_FETCH_ADD(thread_serial, 1);
+}
+
+static inline void render_thread_metadata(void) {
+  uint64_t native_thread_id = 0;
+  #ifdef HAVE_GETTID
+    native_thread_id = gettid();
+  #elif HAVE_PTHREAD_THREADID_NP
+    pthread_threadid_np(pthread_self(), &native_thread_id);
+  #else
+    native_thread_id = current_thread_serial; // TODO: Better fallback for Windows?
+  #endif
+
+  char native_thread_name_buffer[64] = "(unnamed)";
+
+  #ifdef HAVE_PTHREAD_GETNAME_NP
+    pthread_getname_np(pthread_self(), native_thread_name_buffer, sizeof(native_thread_name_buffer));
+  #endif
+
+  fprintf(output_file,
+    "  {\"ph\": \"M\", \"pid\": %u, \"tid\": %u, \"name\": \"thread_name\", \"args\": {\"name\": \"%lu %s\"}},\n",
+    process_id, current_thread_serial, native_thread_id, native_thread_name_buffer
+  );
+}
+
 static VALUE tracing_start(VALUE _self, VALUE output_path) {
   Check_Type(output_path, T_STRING);
 
@@ -63,7 +110,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 +121,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 +139,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 +163,20 @@ 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();
+
+  if (!current_thread_serial_set) {
+    initialize_thread_id();
+    render_thread_metadata();
+  }
+
+  unsigned int thread_id = current_thread_serial;
 
   // 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 +190,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/gvl-tracing.gemspec

@@ -36,13 +36,13 @@ Gem::Specification.new do |spec|
   spec.summary = "Get a timeline view of Global VM Lock usage in your Ruby app"
   spec.homepage = "https://github.com/ivoanjo/gvl-tracing"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.2.0.dev"
+  spec.required_ruby_version = ">= 3.2.0"
 
   # 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(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
-      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features|examples)/|\.(?:git|travis|circleci)|appveyor)})
     end
   end
   spec.require_paths = ["lib", "ext"]

data/lib/gvl_tracing/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gvl-tracing
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Ivo Anjo
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-07-24 00:00:00.000000000 Z
+date: 2023-02-11 00:00:00.000000000 Z
 dependencies: []
 description: 
 email:
@@ -24,8 +24,6 @@ files:
 - LICENSE
 - README.adoc
 - Rakefile
-- examples/example1.json.gz
-- examples/example1.rb
 - ext/gvl_tracing_native_extension/extconf.rb
 - ext/gvl_tracing_native_extension/gvl_tracing.c
 - gems.rb
@@ -46,14 +44,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0.dev
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.0.dev
+rubygems_version: 3.4.1
 signing_key: 
 specification_version: 4
 summary: Get a timeline view of Global VM Lock usage in your Ruby app

data/examples/example1.rb

@@ -1,18 +0,0 @@
-require "gvl-tracing"
-
-def fib(n)
-  return n if n <= 1
-  fib(n - 1) + fib(n - 2)
-end
-
-GvlTracing.start("example1.json")
-
-Thread.new { sleep(0.05) while true }
-
-sleep(0.05)
-
-3.times.map { Thread.new { fib(37) } }.map(&:join)
-
-sleep(0.05)
-
-GvlTracing.stop