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

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:

[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:

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

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

== Experimental features

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

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