`gvl-tracing`

A Ruby gem for getting a timeline view of Global VM Lock usage in your Ruby app that can be analyzed using the Perfetto UI.

For instructions and examples on how to use it, see my RubyKaigi 2023 talk on "Understanding the Ruby Global VM Lock by observing it".

Note	This gem only works on Ruby 3.2 and above because it depends on the GVL Instrumentation API. Furthermore, the GVL Instrumentation API does not (as of Ruby 3.2 and 3.3) currently work on Microsoft Windows.

Quickest start

You can play with the output of running the following example:

require "gvl-tracing"

def fib(n)
  return n if n <= 1
  fib(n - 1) + fib(n - 2)
end

GvlTracing.start("example1.json", os_threads_view_enabled: false) do
  Thread.new { sleep(0.05) while true }

  sleep(0.05)

  3.times.map { Thread.new { fib(37) } }.map(&:join)

  sleep(0.05)
end

To do so:

Download examples/example1.json.gz
Navigate to https://ui.perfetto.dev/ and use the Open trace file option to load the file

Installation

Install the gem and add to the application’s Gemfile or gems.rb file by executing:

$ bundle add gvl-tracing

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install gvl-tracing

Usage

Use require "gvl-tracing" to load the gem.

This gem only provides a single module (GvlTracing) with methods:

start(filename, &block): Starts tracing, writing the results to the provided filename. When a block is passed, yields the block and calls stop.
stop: Stops tracing

The resulting traces can be analyzed by going to Perfetto UI.

Experimental features

Sleep tracking: Add require 'gvl_tracing/sleep_tracking' to add a more specific sleeping state for sleeps (which are otherwise rendered as waiting without this feature)
OS threads view: Pass in os_threads_view_enabled: true to GvlTracing.start to also render a view of Ruby thread activity from the OS native threads point-of-view. This is useful when using M:N thread scheduling, which is used on Ruby 3.3+ Ractors, and when using the RUBY_MN_THREADS=1 setting.

Tips

You can "embed" links to the perfetto UI which trigger loading of a trace by following the instructions on https://perfetto.dev/docs/visualization/deep-linking-to-perfetto-ui .

This way you can actually link from your dashboards and similar pages directly to a trace.

Development

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. To run specs, run bundle exec rake spec.

To run all actions (build the extension, check linting, and run specs), run bundle exec rake.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/ivoanjo/gvl-tracing. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

Code of Conduct

Everyone interacting in the gvl-tracing project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.