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.

There’s a few blog posts and conference talks about what this gem is and how to read its results:

• m:n scheduling and how the (ruby) global vm lock impacts app performance

• understanding the ruby global vm lock by observing it

• ruby’s unexpected i/o vs cpu unfairness

• tracing ruby’s (global) vm lock (Also available [in Japanese and in Korean)

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 this writing) 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:

1. Download examples/example1.json.gz

2. 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.

What do each of the events mean?

The following events are shown in the timeline:

• started_tracing: First event, when GvlTracing is enabled

• stopped_tracing: Last event, when GvlTracing is disabled

• started: Ruby thread created

• died: Ruby thread died

• wants_gvl: Ruby thread is ready to execute, but needs the GVL before it can do so

• running: Ruby thread is running code (and owns the GVL)

• waiting: Ruby thread is waiting to be waken up when some event happens (IO, timeout)

• gc: Doing garbage collection

• sleeping: Thread called Kernel#sleep

Note that not all events come from the GVL instrumentation API, and some events were renamed vs the "RUBY_INTERNAL_THREAD_EVENT" entries.

Experimental features

1. 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.