CLI tool
rbspy/rbspy avatar
rbspy/rbspy

rbspy: a sampling profiler that attaches to a PID, records, and analyzes later

Sampling CPU profiler for Ruby

2,577 stars108 forksRustMIT

At a glance

What is it?
A sampling CPU profiler for Ruby written in Rust, which attaches to an already-running process by PID rather than asking you to change how you launch it. The interesting parts are the version split between the binary and the library crate, the two libc build targets, and the fact that recorded profiles are Protocol Buffers under gzip.
Who is it for?
rbspy is the right tool when the Ruby process you need to profile is already running and you cannot restart it, which is the situation it was built for, and when you want the record and the analysis kept separate. Check three things first.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly Rust, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 22, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • rbspy/rbspy2,577 ★ · +4
Star history
Repository2026-09-302026-11-22
rbspy/rbspy2.6k2.6k

4 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The crate is version 0.53 while the library instructions say depend on 0.8

Two version statements in the same repository do not agree, and they are about the thing a Rust user needs most.

The package manifest declares `version = "0.53.0"`, which matches the v0.53.0 release tag published on 2026-09-24. The library installation section tells you to add this to your Cargo.toml:

toml
[dependencies]
rbspy = "0.8"

So the crate built from this repository is on the 0.53 line and the version the documentation tells a consumer to depend on is 0.8. Nothing on the page bridges that gap. Either the library instruction is a long way behind the binary, or the library is published on a separate version track from the executable, and the page does not say which.

The instability warning sits directly under that snippet and is worth taking seriously: the crate's API is not stable yet, and semantic versioning will be followed after rbspy reaches version 1.0. At 0.53 the promise is deferred indefinitely by its own terms.

Related to the versioning is a second crate in the workspace, `rbspy-ruby-structs`, pinned to 0.53.0 and referenced by path. The workspace has two members beyond the main package, that one and `xtask`, so the Ruby internal structure definitions live in their own crate rather than inside the profiler.

Two libc build targets and the wrong one fails at load time

Linux release binaries come in two flavours and the distinction is not cosmetic.

Binaries tagged `musl` are statically linked against musl libc and can be used on most systems. Binaries tagged `gnu` are dynamically linked against GNU libc, so you need GNU libc installed to run them. That means the tag you pick determines whether the binary carries its own libc or expects one, and getting it wrong produces a loader error rather than anything rbspy can report.

The manifest shows the platform-specific dependency sets behind those builds. Under `cfg(unix)` it pulls in `nix` with the user feature, which is how it reads process ownership. Under `cfg(target_os="macos")` it uses `libproc`. Under `cfg(windows)` it uses `winapi` with the handleapi, timeapi and wow64apiset features, which is the set needed to inspect another process's memory from a 64-bit host.

On macOS the documented route is Homebrew with `brew install rbspy`. On Linux the standalone route is to download a release, unpack it, and move the `rbspy` binary to `/usr/local/bin`. Both are simple, and the musl versus gnu choice is the only decision in the standalone path that needs thought.

Recorded profiles are protobuf under gzip, which is why prost and flate2 are here

The dependency list is the clearest statement of the architecture, and a few entries explain the on-disk format.

`prost` is the Protocol Buffers implementation and `flate2` is gzip compression. Together they mean the raw profiling data saved to disk is a protobuf message, compressed. That is the format the record step writes and the report step reads, and it is why the workflow is split into recording and analyzing at all: you capture once, then you decode and render as many times as you want.

For rendering, `inferno` is the flame graph library, and `terminal_size` is how the tool knows how wide the terminal is before drawing one. `chrono` supplies timestamps.

The sampling machinery itself is not all in this repository. `spytools` is the crate that does the actual stack sampling, and `remoteprocess` is what lets rbspy read and control a process it did not launch. rbspy is the layer that ties a PID, a Ruby runtime's internal layout and a recording together.

Three other dependencies explain design decisions rather than features. `rand` is there because a sampling profiler needs randomized sampling intervals. `ctrlc` means interrupt handling is deliberate, which is what you want in a tool whose output would otherwise be lost on Ctrl-C. And `semver` is a version comparison library, which connects to the Ruby version question below.

A new Ruby release is a recurring task with its own checklist at the root

The repository carries a file called `NEW_RUBY_VERSION_CHECKLIST.md` at its top level, and that filename is the honest description of how this project relates to Ruby releases.

A sampling profiler for MRI has to know how Ruby's internal objects are laid out in memory to turn an address into a method name and a file. Those layouts are not a stable public interface; they change between Ruby versions. `rbspy-ruby-structs` is the workspace crate holding those definitions, and `semver` sits in the dependency list so the tool can compare the Ruby version it is attached to.

So supporting a new Ruby is not a dependency bump. It is a checklist, and the project keeps it as a visible document rather than as a commit message.

The tree also shows the release machinery: `RELEASE_CHECKLIST.md`, a `ci/` directory, an `xtask/` workspace member for running project tasks, a `config.toml` at the root, a `.cargo/` directory, a `.dockerignore`, and a `logo/` directory. Publishing configuration is not incidental here either, since the manifest excludes three paths from the crate tarball.

The manifest sets `rust-version = "1.85"` and `edition = "2021"`, so there is a declared minimum Rust version, and `[profile.release]` turns on link-time optimization.

The examples directory is named after the three documented activities

There are four entries under `examples/`: `record.rs`, `report.rs`, `snapshot.rs` and an `include/` directory.

The three file names line up exactly with the three things the project says it can do. Recording is the first step: attach to a PID and sample. Analysis is the second: read what you recorded and render it, in a variety of ways, later. A snapshot is the third, and the naming implies the one-shot case where you want a picture of what a process is doing without setting up a recording at all.

`examples/include/` is a fourth thing that the file names imply but the top-level page never mentions. Something in this repository is a library meant to be included by other Rust code, and the examples directory is where that is demonstrated. The library warning about API instability applies to that usage as much as to the binary.

So the tree and the prose agree on the shape of the tool: attach, capture, keep, then interpret. The one part the tree suggests and the documentation leaves out is the include path, which is consistent with a crate whose API is not yet stable and is therefore not advertised.

The documentation URL in the manifest points at the repository, not the docs site

Two manifest fields are set in the order most projects do not set them.

`homepage` is `https://rbspy.github.io/`, which is the documentation site and the same address the documentation section of the README gives. `documentation` is `https://github.com/rbspy/rbspy`, which is the repository itself.

So the field crates.io renders as the documentation link for the crate sends you to the source, and the field it renders as the homepage sends you to the manual. Anyone arriving through the crate listing gets the README by way of the documentation link, which is a reasonable outcome, but it is the reverse of the usual arrangement and it means neither field tells you where the manual is except by accident.

The project itself keeps the distinction clear elsewhere. It points at `https://rbspy.github.io` for documentation, at `https://rbspy.github.io/installing.html` for a fuller installation guide than the README carries, and at two separate checklist issues for the two conventions it wants community help with: a GitHub issue for adding a success story, and the issue tracker as the recommended place to ask questions.

That last one is unusual and worth noting. Success stories are collected as comments in a specific issue thread rather than stored in the repository, so the project's record of who it has helped lives in an issue, not in a file.

Rust was chosen to lower the barrier for contributors who would otherwise need C

The contributing section states a design rationale rather than a recruitment pitch.

It says a major reason rbspy is written in Rust is that Rust is more approachable for beginners than C/C++, and that contributors who are not very experienced Rust programmers are very welcome. Rust is named as the more approachable of the two for people new to systems work, with a pointer to the Rust language resources.

That reads as a deliberate consequence of what the tool does. A sampling profiler has to read another process's memory, walk native stacks, and decode a language runtime's internal object layout. In C that is approachable to a much smaller set of newcomers than in Rust, so the language choice is also a contributor policy.

The rest of the contribution guidance is narrow on purpose. Pull requests that improve usability, fix bugs, or help rbspy support more operating systems are the ones wanted, and questions go to a GitHub issue rather than to a discussion board or a chat.

The supported platforms are listed as Linux, Mac, Windows and FreeBSD, with a kernel version of 3.2 or newer required, which the documentation translates for Ubuntu as 12.04 or newer. The asterisk after Linux is present with no visible footnote explaining what it qualifies.

Editorial conclusion

rbspy is the right tool when the Ruby process you need to profile is already running and you cannot restart it, which is the situation it was built for, and when you want the record and the analysis kept separate. Check three things first. The kernel floor is 3.2, which on Ubuntu means 12.04 or newer. Pick your binary deliberately, since musl builds are static and gnu builds need GNU libc present. And if you are planning to embed it as a Rust library rather than run the binary, read the warning: the library API is not stable, semantic versioning is promised only after 1.0, and the documented dependency version does not match the crate version.

Frequently asked questions

How do I profile a Ruby program that is already running with rbspy?

Give it a PID and it starts profiling that process. rbspy is a sampling profiler, described as low overhead and safe to run in production, and you can record profiling data, save the raw data to disk, and analyze it later in a variety of ways. Kernel version 3.2 or newer is required, which means Ubuntu 12.04 or newer.

Which rbspy binary should I download on Linux?

It depends on your libc. Binaries tagged musl are statically linked against musl libc and work on most systems. Binaries tagged gnu are dynamically linked against GNU libc, so GNU libc has to be installed. Either way the standalone route is to download a release, unpack it, and move the rbspy binary to /usr/local/bin.

Is the rbspy Rust library API stable?

No, and the project says so in capitals. The warning states the crate's API is not stable yet and that semantic versioning will be followed after rbspy reaches version 1.0. The library instructions also tell you to depend on version 0.8 while the package manifest declares 0.53.0, so check which line you are actually pulling before you build on it.

What format does rbspy save recorded profiles in?

The dependency list indicates protobuf encoded and gzip compressed. prost is the Protocol Buffers implementation and flate2 is the compression layer, which is what lets a recording be written once and analyzed repeatedly afterwards. Rendering of a saved recording is handled by inferno for flame graphs, with terminal_size consulted for terminal width.

What does it take to build rbspy from source?

Cargo from crates.io, then cargo build and cargo test, and the binary ends up at target/debug/rbspy. The manifest sets rust-version to 1.85 and edition 2021, and release builds enable link-time optimization. The repository is a Cargo workspace with two extra members, rbspy-ruby-structs and xtask.

Official sources

  1. License: MIT
  2. Project website
  3. rbspy/rbspy on GitHub
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/rbspy-rbspy.svg)](https://hysenlabs.com/projects/rbspy-rbspy)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/rbspy-rbspy.svg)](https://hysenlabs.com/projects/rbspy-rbspy)

Was this useful?