This PR introduces a new compilation log to help gain insights into how YJIT is optimizing an application. Finding the correct amount information to display for a given context is a bit hard. Some folks may want an entire log while others are only interested in the most recent events. This PR tries to strike a balance by offering a few different operating modes.

Command-Line Flag

This PR introduces the --yjit-log flag, which functions like a hybrid of --yjit-stats and --yjit-dump-disasm. The presence of an optional argument will dictate where the compilation log is written.

No Argument

--yjit-log without an argument will print the compilation log to $stderr when the application exits. Events are buffered until the application exit in order to avoid mixing messages up with other output from the application. To constrain the total amount of memory used, a circular buffer is used to store the logged events. Only the entries present in the buffer at the time the application exits will be printed.

--yjit-compilation-log without an argument will print the compilation log to $stderr as events occur. It will be logically equivalent to running with --yjit-compilation-log=/dev/stderr, just without file truncation. Events will still be collected in the internal circular buffer for programmatic access.

Quiet Argument

--yjit-log=quiet will activate the log but not print or write it anywhere. The log contents will be accessible in code via RubyVM::YJIT.log. A circular buffer is used to store the log entries to constrain growth. Consequently, only the last N=1024 entries are available. Reading the log will remove all stored values, freeing up space for new entries.

Directory Argument

The --yjit-log flag can take an optional argument pointing at a directory (e.g., --yjit-log=$PWD). In this case, it functions very similarly to --yjit-dump-disasm: a new file named yjit_$PID.log will be created in the specified directory and all compilation events will be logged to that file. In this way, one directory can capture output from multiple processes. NB: the directory must exist when starting Ruby, otherwise the argument will be treated as if it were a file name (see below).

Unlike the case where output is sent to $stderr, all events will be written to the file as they occur. The circular buffer will still be populated in the event you wish to work with the log in memory (accessible via RubyVM::YJIT.compilation_log).

File Argument

The --yjit-log flag can take an optional argument pointing at a file (e.g., --yjit-log=my_compilation.log). This works very similarly to the directory argument case, except instead of a file name being generated, it will use the one supplied.

The file will be created when the process starts. If the file already exists, it will be truncated. This supports a nice workflow whereby you can re-run the same ruby invocation repeatedly and avoid mixing results for multiple runs. Moreover, since the file is truncated rather than re-created, you can tail -f my_compilation.log without having to restart the tail command each time you re-run ruby.

Programmatic Control

In addition to the command-line flag, you can enable or disable the compilation log via RubyVM::YJIT.enable and the compilation_log keyword argument. It is designed to function similarly to the programmatic control of YJIT's runtime stats. Principally, it accepts three values:

• false: Don't enable the compilation log (more of a placeholder since you can't call this method again to disable)
• true: Enable the compilation log and print it to $stderr at exit
• :quiet: Enable the compilation log, but do not write or print it

NB: There is not an option to enable the log and write to a file. If you want to operate in that mode you should supply the --yjit-log argument.

Programmatic Access

Check if Enabled

You can check if the YJIT compilation log is currently enabled with RubyVM::YJIT.log_enabled?.

Reading the Log

The last N=1024 compilation log entries are accessible via RubyVM::YJIT.log. The output has the type Array[Tuple[Time, String]], providing the log is enabled. If it is not, the value will be nil to help differentiate from a log where no compilation has occurred yet (i.e., an empty array) . The log is automatically cleared when accessed so subsequent reads will be guaranteed to contain new events.