DEV Community

Koichi Sasada
Koichi Sasada

Posted on

Lumitrace: See What Your Ruby Code Is Actually Doing, Instantly

#ruby

ko1 note: This article is written by Claude code.
ko1 note: lumitrace itself is written by Codex.

Time to ditch puts debugging.

We've all been there. "What's in this variable again?" So you sprinkle p value everywhere, run the script, delete the prints, add more somewhere else...

With Lumitrace, you can record the value of every expression without touching your code at all.

Install 

gem install lumitrace
Enter fullscreen mode Exit fullscreen mode

One Command Is All You Need 

lumitrace your_script.rb
Enter fullscreen mode Exit fullscreen mode

That's it. Every line's result shows up inline:

 5|   base = n + 1                 #=> 3 (3rd run)
 6|   scaled = Sample2.scale(base) #=> 6 (3rd run)
 7|   squares = Sample3.series(n)  #=> [1, 4] (3rd run)
Enter fullscreen mode Exit fullscreen mode

You can see how many times each line ran. No more lining up five puts statements to track a loop.

Beautiful HTML Reports 

lumitrace -h your_script.rb
Enter fullscreen mode Exit fullscreen mode

This generates an HTML report you can open in your browser. It comes with a file tree, line coverage, and clear markers: 🔎 for executed expressions, ∅ for unexecuted ones. Spotting dead code takes a glance.

ko1 note: generated sample HTML

Share the URL with a teammate and they'll land on the exact same file and line.

The Ultimate Debugging Flow for Failing Tests

A test just failed. The logs aren't helping. Here's what you do:

lumitrace -t exec rake test
Enter fullscreen mode Exit fullscreen mode

Run your entire test suite through Lumitrace and see the actual values around the failure.
"Expected 5 but got 3. Why?" -- every intermediate computation is recorded, so the answer is right there.

Amazing with AI

This is where Lumitrace really shines.

lumitrace --collect-mode last -j exec rake test
Enter fullscreen mode Exit fullscreen mode

Dump runtime values as JSON and hand them straight to an AI. Instead of guessing from source code alone, the AI can see what actually happened -- and its accuracy goes through the roof.

Drop this snippet into your project's CLAUDE.md or AGENTS.md and AI agents will pick it up on their own:

## Debugging (Lumitrace)
lumitrace is a tool that records runtime values of each Ruby expression.
When a test fails, read `lumitrace help` first, then use it.
Basic: `lumitrace -t exec rake test`
Enter fullscreen mode Exit fullscreen mode

ko1 note: I haven't actually tried this myself yet... If anyone gives it a shot and it works, please let me know!

Trace Only What You Changed with git diff 

lumitrace -g your_script.rb
Enter fullscreen mode Exit fullscreen mode

The -g flag traces only lines touched by git diff. Even on large projects the output stays compact. Perfect for a quick sanity check before opening a PR.

Works in CI Too

Enable Lumitrace in GitHub Actions, upload the HTML report to Pages, and your whole team can browse the runtime values of a failing test right from the browser.

Cheat Sheet

Goal Command
Quick look lumitrace your_script.rb
HTML report lumitrace -h your_script.rb
Trace tests lumitrace -t exec rake test
Feed to AI lumitrace --collect-mode last -j exec rake test
Changed lines only lumitrace -g your_script.rb

Reclaim the time you've been spending on puts debugging.

Check out the tutorial for the full guide.

ko1 note: There is a Ruby playground powered by Lumitrace: https://ko1.github.io/lumitrace/runv/

Top comments (0)