gvltools 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 42d6e3f8ea2cc420e17a413a62fba51ccb6c2b90dac11138186e9f4d203bed51
+  data.tar.gz: 97576f44774bb991699152d36140714b792e17ced8a7ea48d1210f0c8d94b1df
+SHA512:
+  metadata.gz: ae23c00ab1f94c2af17753f5ba847690ebea31cb0d3f23134080ad34a475686ac0d9872fa56025a1fab8135c5ee57c58e19675bbc08160c9444a8d30edb847db
+  data.tar.gz: 54e1694fd5d16935c98a6b838fdf188427cf645f0fe00ac08a7323609c70f01721d9836b80c6bdf2096ee7341d4d39a44f713b20a770470072c72c48887564c3

data/.rubocop.yml

@@ -0,0 +1,41 @@
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  SuggestExtensions: false
+
+Lint/DuplicateMethods:
+  Exclude:
+    - lib/gvltools.rb # we need the self alias trick to avoid warnings
+
+Style/Alias:
+  EnforcedStyle: prefer_alias_method
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/GlobalVars:
+  Exclude:
+    - ext/**/extconf.rb
+
+Style/Documentation:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 120
+
+Gemspec/RequiredRubyVersion:
+  Enabled: false
+
+Gemspec/RequireMFA:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2022-06-14
+
+- Initial release

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,47 @@
+PATH
+  remote: .
+  specs:
+    gvltools (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    minitest (5.15.0)
+    parallel (1.22.1)
+    parser (3.1.2.0)
+      ast (~> 2.4.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    rake-compiler (1.2.0)
+      rake
+    regexp_parser (2.5.0)
+    rexml (3.2.5)
+    rubocop (1.30.1)
+      parallel (~> 1.10)
+      parser (>= 3.1.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.18.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.18.0)
+      parser (>= 3.1.1.0)
+    ruby-progressbar (1.11.0)
+    unicode-display_width (2.1.0)
+
+PLATFORMS
+  arm64-darwin-21
+  arm64-darwin-22
+  x86_64-linux
+
+DEPENDENCIES
+  gvltools!
+  minitest (~> 5.0)
+  rake (~> 13.0)
+  rake-compiler
+  rubocop (~> 1.21)
+
+BUNDLED WITH
+   2.3.14

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Shopify
+
+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,138 @@
+# GVLTools
+
+Set of GVL instrumentation tools
+
+## Requirements
+
+GVLTools uses the GVL instrumentation API added in Ruby 3.2.0.
+
+To make it easier to use, on older Rubies the gem will install and expose the same methods, but they won't have any effect and all metrics will report `0`.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add gvltools
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install gvltools
+
+## Usage
+
+GVLTools expose metric modules with a common interface, for instance `GVLTools::LocalTimer`:
+
+```ruby
+GVLTools::LocalTimer.enable
+GVLTools::LocalTimer.disable
+GVLTools::LocalTimer.enabled? # => true / false
+GVLTools::LocalTimer.reset
+```
+
+By default, all metrics are disabled.
+
+Note that using the GVL instrumentation API adds some overhead each time Ruby has to switch threads.
+In production it is recommended to only enable it on a subset of processes or for small periods of time as to not impact
+the average latency too much.
+
+The exact overhead is not yet known, early testing showed a `1-5%` slowdown on a fully saturated multi-threaded app.
+
+### LocalTimer
+
+`LocalTimer` records the overall time spent waiting on the GVL by the current thread.
+It is particularly useful to detect wether an application use too many threads, and how much latency is impacted.
+For instance as a Rack middleware:
+
+```ruby
+class GVLInstrumentationMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    before = GVLTools::LocalTimer.monotonic_time
+    response = @app.call(env)
+    diff = GVLTools::LocalTimer.monotonic_time - before
+    puts "Waited #{diff} nanoseconds on the GVL"
+    response
+  end
+end
+```
+
+### GlobalTimer
+
+`GlobalTimer` records the overall time spent waiting on the GVL by all threads combined.
+
+```ruby
+def fibonacci(number)
+  number <= 1 ? number : fibonacci(number - 1) + fibonacci(number - 2)
+end
+
+before = GVLTools::GlobalTimer.monotonic_time
+threads = 5.times.map do
+  Thread.new do
+    5.times do
+      fibonacci(30)
+    end
+  end
+end
+threads.each(&:join)
+diff = GVLTools::GlobalTimer.monotonic_time - before
+puts "Waited #{(diff / 1_000_000.0).round(1)}ms on the GVL"
+```
+
+outputs:
+
+```
+Waited 4122.8ms on the GVL
+```
+
+### WaitingThreads
+
+`WaitingThreads` records how many threads are currently waiting on the GVL to start executing code.
+
+```ruby
+def fibonacci(number)
+  number <= 1 ? number : fibonacci(number - 1) + fibonacci(number - 2)
+end
+
+Thread.new do
+  10.times do
+    sleep 0.001
+    p GVLTools::WaitingThreads.count
+  end
+end
+
+threads = 5.times.map do
+  Thread.new do
+    5.times do
+      fibonacci(30)
+    end
+  end
+end
+threads.each(&:join)
+```
+
+Outputs:
+
+```
+5
+5
+4
+```
+
+It's less precise than timers, but the instrumentation overhead is lower.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. 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 the created tag, 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/Shopify/gvltools.
+
+## 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,39 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+has_ext = RUBY_ENGINE == "ruby" && RUBY_VERSION >= "3.2"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = has_ext ? FileList["test/**/test_*.rb"] : FileList["test/fallback/**/test_*.rb"]
+  t.warning = true
+  t.verbose = true
+end
+
+if has_ext
+  require "rake/extensiontask"
+
+  Rake::ExtensionTask.new("instrumentation") do |ext|
+    ext.ext_dir = "ext/gvltools"
+    ext.lib_dir = "lib/gvltools"
+  end
+else
+  task :compile do
+    # noop
+  end
+
+  task :clean do
+    # noop
+  end
+end
+
+Rake::Task["test"].enhance(["compile"])
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/ext/gvltools/extconf.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "mkmf"
+if RUBY_ENGINE == "ruby" && have_func("rb_internal_thread_add_event_hook", ["ruby/thread.h"])
+  $CFLAGS << " -O3 -Wall "
+  create_makefile("gvltools/instrumentation")
+else
+  File.write("Makefile", dummy_makefile($srcdir).join)
+end

data/ext/gvltools/instrumentation.c

@@ -0,0 +1,175 @@
+#include <time.h>
+#include <ruby.h>
+#include <ruby/thread.h>
+#include <ruby/atomic.h>
+
+// Metrics
+static rb_internal_thread_event_hook_t *gt_hook = NULL;
+
+static unsigned int enabled_mask = 0;
+#define TIMER_GLOBAL        1 << 0
+#define TIMER_LOCAL         1 << 1
+#define WAITING_THREADS     1 << 2
+
+#define ENABLED(metric) (enabled_mask & (metric))
+
+#if __STDC_VERSION__ >= 201112
+  #define THREAD_LOCAL_SPECIFIER _Thread_local
+#elif defined(__GNUC__) && !defined(RB_THREAD_LOCAL_SPECIFIER_IS_UNSUPPORTED)
+  /* note that ICC (linux) and Clang are covered by __GNUC__ */
+  #define THREAD_LOCAL_SPECIFIER __thread
+#endif
+
+// Common
+#define SECONDS_TO_NANOSECONDS (1000 * 1000 * 1000)
+
+static THREAD_LOCAL_SPECIFIER bool was_ready = 0;
+
+static inline void gt_gettime(struct timespec *time) {
+    if (clock_gettime(CLOCK_MONOTONIC, time) == -1) {
+        rb_sys_fail("clock_gettime");
+    }
+}
+
+static inline rb_atomic_t gt_time_diff_ns(struct timespec before, struct timespec after) {
+    rb_atomic_t total = 0;
+    total += (after.tv_nsec - before.tv_nsec);
+    total += (after.tv_sec - before.tv_sec) * SECONDS_TO_NANOSECONDS;
+    return total;
+}
+
+static VALUE gt_metric_enabled_p(VALUE module, VALUE metric) {
+    return ENABLED(NUM2UINT(metric)) ? Qtrue : Qfalse;
+}
+
+static void gt_thread_callback(rb_event_flag_t event, const rb_internal_thread_event_data_t *event_data, void *user_data);
+static VALUE gt_enable_metric(VALUE module, VALUE metric) {
+    enabled_mask |= NUM2UINT(metric);
+    if (!gt_hook) {
+        gt_hook = rb_internal_thread_add_event_hook(
+            gt_thread_callback,
+            RUBY_INTERNAL_THREAD_EVENT_EXITED | RUBY_INTERNAL_THREAD_EVENT_READY | RUBY_INTERNAL_THREAD_EVENT_RESUMED,
+            NULL
+        );
+    }
+    return Qtrue;
+}
+
+static VALUE gt_disable_metric(VALUE module, VALUE metric) {
+    if (ENABLED(NUM2UINT(metric))) {
+        enabled_mask -= NUM2UINT(metric);
+    }
+    if (!enabled_mask && gt_hook) {
+        rb_internal_thread_remove_event_hook(gt_hook);
+        gt_hook = NULL;
+    }
+    return Qtrue;
+}
+
+// GVLTools::LocalTimer and GVLTools::GlobalTimer
+static rb_atomic_t global_timer_total = 0;
+static THREAD_LOCAL_SPECIFIER uint64_t local_timer_total = 0;
+static THREAD_LOCAL_SPECIFIER struct timespec timer_ready_at = {0};
+
+static VALUE global_timer_monotonic_time(VALUE module) {
+    return UINT2NUM(global_timer_total);
+}
+
+static VALUE global_timer_reset(VALUE module) {
+    RUBY_ATOMIC_SET(global_timer_total, 0);
+    return Qtrue;
+}
+
+static VALUE local_timer_monotonic_time(VALUE module) {
+    return ULL2NUM(local_timer_total);
+}
+
+static VALUE local_timer_reset(VALUE module) {
+    local_timer_total = 0;
+    return Qtrue;
+}
+
+// Thread counts
+static rb_atomic_t waiting_threads_total = 0;
+
+static VALUE waiting_threads_count(VALUE module) {
+    return UINT2NUM(waiting_threads_total);
+}
+
+static VALUE waiting_threads_reset(VALUE module) {
+    RUBY_ATOMIC_SET(waiting_threads_total, 0);
+    return Qtrue;
+}
+
+// General callback
+static void gt_reset_thread_local_state(void) {
+    // MRI can re-use native threads, so we need to reset thread local state,
+    // otherwise it will leak from one Ruby thread from another.
+    was_ready = false;
+    local_timer_total = 0;
+}
+
+static void gt_thread_callback(rb_event_flag_t event, const rb_internal_thread_event_data_t *event_data, void *user_data) {
+    switch(event) {
+        case RUBY_INTERNAL_THREAD_EVENT_STARTED:
+        case RUBY_INTERNAL_THREAD_EVENT_EXITED: {
+            gt_reset_thread_local_state();
+        }
+        break;
+        case RUBY_INTERNAL_THREAD_EVENT_READY: {
+            if (!was_ready) was_ready = true;
+
+            if (ENABLED(WAITING_THREADS)) {
+                RUBY_ATOMIC_INC(waiting_threads_total);
+            }
+
+            if (ENABLED(TIMER_GLOBAL | TIMER_LOCAL)) {
+                gt_gettime(&timer_ready_at);
+            }
+        }
+        break;
+        case RUBY_INTERNAL_THREAD_EVENT_RESUMED: {
+            if (!was_ready) break; // In case we registered the hook while some threads were already waiting on the GVL
+
+            if (ENABLED(WAITING_THREADS)) {
+                RUBY_ATOMIC_DEC(waiting_threads_total);
+            }
+
+            if (ENABLED(TIMER_GLOBAL | TIMER_LOCAL)) {
+                struct timespec current_time;
+                gt_gettime(&current_time);
+                rb_atomic_t diff = gt_time_diff_ns(timer_ready_at, current_time);
+
+                if (ENABLED(TIMER_LOCAL)) {
+                    local_timer_total += diff;
+                }
+
+                if (ENABLED(TIMER_GLOBAL)) {
+                    RUBY_ATOMIC_ADD(global_timer_total, diff);
+                }
+            }
+        }
+        break;
+    }
+}
+
+void Init_instrumentation(void) {
+    VALUE rb_mGVLTools = rb_const_get(rb_cObject, rb_intern("GVLTools"));
+
+    VALUE rb_mNative = rb_const_get(rb_mGVLTools, rb_intern("Native"));
+    rb_define_singleton_method(rb_mNative, "enable_metric", gt_enable_metric, 1);
+    rb_define_singleton_method(rb_mNative, "disable_metric", gt_disable_metric, 1);
+    rb_define_singleton_method(rb_mNative, "metric_enabled?", gt_metric_enabled_p, 1);
+
+    VALUE rb_mGlobalTimer = rb_const_get(rb_mGVLTools, rb_intern("GlobalTimer"));
+    rb_define_singleton_method(rb_mGlobalTimer, "reset", global_timer_reset, 0);
+    rb_define_singleton_method(rb_mGlobalTimer, "monotonic_time", global_timer_monotonic_time, 0);
+
+    VALUE rb_mLocalTimer = rb_const_get(rb_mGVLTools, rb_intern("LocalTimer"));
+    rb_define_singleton_method(rb_mLocalTimer, "reset", local_timer_reset, 0);
+    rb_define_singleton_method(rb_mLocalTimer, "monotonic_time", local_timer_monotonic_time, 0);
+
+    VALUE rb_mWaitingThreads = rb_const_get(rb_mGVLTools, rb_intern("WaitingThreads"));
+    rb_define_singleton_method(rb_mWaitingThreads, "reset", waiting_threads_reset, 0);
+    rb_define_singleton_method(rb_mWaitingThreads, "count", waiting_threads_count, 0);
+}

data/gvltools.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/gvltools/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "gvltools"
+  spec.version = GVLTools::VERSION
+  spec.authors = ["Jean Boussier"]
+  spec.email = ["jean.boussier@gmail.com"]
+
+  spec.summary = "Set of GVL instrumentation tools"
+  spec.homepage = "https://github.com/Shopify/gvltools"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/master/CHANGELOG.md"
+
+  # 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)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+  spec.extensions = ["ext/gvltools/extconf.rb"]
+
+  spec.add_development_dependency "rake-compiler"
+end

data/lib/gvltools/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GVLTools
+  VERSION = "0.1.0"
+end

data/lib/gvltools.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative "gvltools/version"
+
+module GVLTools
+  class Error < StandardError; end
+
+  module Native
+    class << self
+      def enable_metric(_metric)
+        false
+      end
+      alias_method :enable_metric, :enable_metric
+
+      def disable_metric(_metric)
+        false
+      end
+      alias_method :disable_metric, :disable_metric
+
+      def metric_enabled?(_metric)
+        false
+      end
+      alias_method :metric_enabled?, :metric_enabled?
+    end
+  end
+
+  module AbstractInstrumenter
+    TIMER_GLOBAL = 1 << 0
+    TIMER_LOCAL = 1 << 1
+    WAITING_THREADS = 1 << 2
+
+    def enabled?
+      Native.metric_enabled?(metric)
+    end
+
+    def enable
+      Native.enable_metric(metric)
+    end
+
+    def disable
+      Native.disable_metric(metric)
+    end
+
+    def reset
+      false
+    end
+
+    private
+
+    def metric
+      raise NotImplementedError
+    end
+  end
+  private_constant :AbstractInstrumenter
+
+  module GlobalTimer
+    extend AbstractInstrumenter
+
+    class << self
+      def monotonic_time
+        0
+      end
+      alias_method :monotonic_time, :monotonic_time
+
+      private
+
+      def metric
+        TIMER_GLOBAL
+      end
+    end
+  end
+
+  module LocalTimer
+    extend AbstractInstrumenter
+
+    class << self
+      def monotonic_time
+        0
+      end
+      alias_method :monotonic_time, :monotonic_time
+
+      private
+
+      def metric
+        TIMER_LOCAL
+      end
+    end
+  end
+
+  module WaitingThreads
+    extend AbstractInstrumenter
+
+    class << self
+      def count
+        0
+      end
+      alias_method :count, :count
+
+      private
+
+      def metric
+        WAITING_THREADS
+      end
+    end
+  end
+
+  begin
+    require "gvltools/instrumentation"
+  rescue LoadError
+    # No native ext.
+  end
+
+  private_constant :Native
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: gvltools
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jean Boussier
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-01-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email:
+- jean.boussier@gmail.com
+executables: []
+extensions:
+- ext/gvltools/extconf.rb
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- ext/gvltools/extconf.rb
+- ext/gvltools/instrumentation.c
+- gvltools.gemspec
+- lib/gvltools.rb
+- lib/gvltools/version.rb
+homepage: https://github.com/Shopify/gvltools
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/Shopify/gvltools
+  source_code_uri: https://github.com/Shopify/gvltools
+  changelog_uri: https://github.com/Shopify/gvltools/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key:
+specification_version: 4
+summary: Set of GVL instrumentation tools
+test_files: []