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. |
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") 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
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
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.
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.
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
.
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.
Everyone interacting in the gvl-tracing project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.