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

See my blog post https://ivoanjo.me/blog/2022/07/17/tracing-ruby-global-vm-lock/[tracing ruby's (global) vm lock] for more details!

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

== 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") 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].

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

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