gvl-tracing

= 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[]

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

• https://ivoanjo.me/blog/2025/03/30/mn-scheduling-and-how-the-ruby-gvl-impacts-app-perf/[m:n scheduling and how the (ruby) global vm lock impacts app performance]
• https://ivoanjo.me/blog/2023/07/23/understanding-the-ruby-global-vm-lock-by-observing-it/[understanding the ruby global vm lock by observing it]
• https://ivoanjo.me/blog/2023/02/11/ruby-unexpected-io-vs-cpu-unfairness/[ruby’s unexpected i/o vs cpu unfairness]
• https://ivoanjo.me/blog/2022/07/17/tracing-ruby-global-vm-lock/[tracing ruby’s (global) vm lock] (Also available [https://techracho.bpsinc.jp/hachi8833/2022_09_02/120530[in Japanese] and https://velog.io/@heka1024/%EB%B2%88%EC%97%AD-tracing-rubys-global-vm-lock[in Korean])

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 this writing) currently work on Microsoft Windows.

== Quickest start

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

[source,ruby]

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 link:https://github.com/ivoanjo/gvl-tracing/blob/master/examples/example1.json.gz?raw=true[`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:

[source,bash]

$ bundle add gvl-tracing

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

[source,bash]

$ 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 https://ui.perfetto.dev/[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

• 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 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].