- Latest (GraalVM for JDK 21)
- Dev Build
- GraalVM for JDK 21
- GraalVM for JDK 20
- GraalVM for JDK 17
- GraalVM 22.3
- GraalVM 22.2
- GraalVM 22.1
- GraalVM 22.0
- GraalVM 21.3
- Java on Truffle
- LLVM Languages Reference
- Python Reference
- Ruby Reference
- Debugging Ruby
- Runtime Configurations
- Using Ruby with GraalVM
- Installing `libssl`
- Installing LibYAML
- Installing Make and GCC
- Installing `zlib`
- Migration from JRuby to Ruby
- TruffleRuby Options and Command Line
- Polyglot Programming
- Ruby Managers and Installers
- Standalone Distribution
- Development Tools for Ruby
- Ruby Additional Functionality
- Setting up a UTF-8 Locale
- Reporting Performance Problems
- Optcarrot Example
- R Reference
- WebAssembly Reference
TruffleRuby, like other GraalVM languages, supports 2 standard debugging protocols:
- the Debug Adapter Protocol (DAP), best supported
- the Chrome DevTools Protocol, limited support because the protocol does not handle threads
Also see Tools for more tools besides just debuggers.
First install the GraalVM VSCode extension.
Then follow this documentation to debug TruffleRuby with VSCode.
Unfortunately RubyMine / IntelliJ IDEA do not support the Debug Adapter Protocol yet for Ruby debugging.
Please vote or comment on the feature request to share your interest.
Command-line Debugging Options #
Printing Exceptions #
There are two ways to print exceptions, which can be useful to find the source of an error:
- the standard Ruby
-dflag which prints the
file:linewhere each exception was raised
--backtraces-raisewhich show the full backtrace on each exception raised
Both print all exceptions even if the exceptions are later rescued.
Java exceptions can be printed with
--exceptions-* options for more possibilities.
Printing Stacktraces and Backtraces of a Running Process #
One can send the
SIGQUIT signal to TruffleRuby to make it print the Java stacktraces of all threads.
Ctrl + \ can be used to send
SIGQUIT to the current process in a terminal.
This is useful to debug hangs and deadlocks, or to know what the process is doing.
This works on both TruffleRuby Native and JVM.
SIGALRM to a TruffleRuby process will print the Ruby backtraces of all threads.
More Information in Backtraces #
TruffleRuby tries to match MRI’s backtrace format as closely as possible. This sometimes means that extra available information is not displayed. When debugging you may want to see this information.
An option to show more information is
--backtraces-interleave-java=true, which shows you the Java methods involved in executing each Ruby method.
When you are interoperating with other languages, including C extensions, backtraces for Java exceptions may be missing information, as the Java frames are gone by the time Ruby has a chance to format them into a backtrace.
Printing Subprocesses #
You can log subprocesses created by TruffleRuby using the option
$ ruby --log-subprocess -e '`ls .`' [ruby] INFO: spawn: ls .
This is not transitive though, unless you set this option in
Printing TruffleRuby Processes and Arguments #
You can log TruffleRuby processes created using the
bin/truffleruby launcher and their arguments with
$ ruby --log-process-args -e 0 [ruby] INFO: new process: truffleruby --log-process-args -e 0
You can set this option in
TRUFFLERUBYOPT to make it apply to TruffleRuby subprocess as well.
Separate log files will be used for different subprocesses running at the same time when using
These log files start with the same path but end with
2, etc suffixes.