= gvl-tracing
:toc:
:toc-placement: macro
:toclevels: 4
:toc-title:
A Ruby gem for getting a timeline view of Global VM Lock usage in your Ruby app that can be analyzed using the https://ui.perfetto.dev/[Perfetto UI].
image::preview.png[]
For instructions and examples on how to use it, see my https://ivoanjo.me/blog/2023/07/23/understanding-the-ruby-global-vm-lock-by-observing-it/[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 https://github.com/ruby/ruby/pull/5500[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") do Thread.new { sleep(0.05) while true }
sleep(0.05)
3.times.map { Thread.new { fib(37) } }.map(&:join)
To do so:
== Installation
Install the gem and add to the application's Gemfile
or gems.rb
file by executing:
If bundler is not being used to manage dependencies, install the gem by executing:
== 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 tracingThe resulting traces can be analyzed by going to https://ui.perfetto.dev/[Perfetto UI].
== 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 https://rubygems.org[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 https://github.com/ivoanjo/gvl-tracing/blob/master/CODE_OF_CONDUCT.adoc[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 https://github.com/ivoanjo/gvl-tracing/blob/master/CODE_OF_CONDUCT.adoc[code of conduct].