ZJIT: Dump side-exit locations in Fuchsia trace format (ruby#16470)

This gives us instant access to all nice Fuchsia and Perfetto tooling, including zoomable, SQL queryable browsing for traces:

<img width="1912" height="1185" alt="Screenshot 2026-03-20 at 10 50 57 AM" src="https://github.com/user-attachments/assets/6475bbec-eb55-4886-8e94-13450def2de5" />

Hottest side-exits grouped by exit location using SQL:

```sql
SELECT reason, backtrace, count(*) AS exits FROM (
  SELECT
    s.id,
    s.name AS reason,
    group_concat(a.display_value, ' <- ') AS backtrace
  FROM slice s
  JOIN args a USING(arg_set_id)
  WHERE s.category = 'side_exit'
  GROUP BY s.id
)
GROUP BY reason, backtrace
ORDER BY exits DESC
LIMIT 30
```

<img width="1912" height="1186" alt="Screenshot 2026-03-24 at 3 58 28 PM" src="https://github.com/user-attachments/assets/8195ccd8-aeb6-4396-8c07-e85bbb280a4a" />

Author: tekknolagi

test/ruby/test_zjit.rb

@@ -383,25 +383,20 @@ def test
   end
 
   def test_exit_tracing
-    # This is a very basic smoke test. The StackProf format
-    # this option generates is external to us.
-    Dir.mktmpdir("zjit_test_exit_tracing") do |tmp_dir|
-      assert_compiles('true', <<~RUBY, extra_args: ['-C', tmp_dir, '--zjit-trace-exits'])
-        def test(object) = object.itself
-
-        # induce an exit just for good measure
-        array = []
-        test(array)
-        test(array)
-        def array.itself = :not_itself
-        test(array)
-
-        RubyVM::ZJIT.exit_locations.is_a?(Hash)
-      RUBY
-      dump_files = Dir.glob('zjit_exits_*.dump', base: tmp_dir)
-      assert_equal(1, dump_files.length)
-      refute(File.empty?(File.join(tmp_dir, dump_files.first)))
-    end
+    # Smoke test: --zjit-trace-exits writes a Fuchsia trace (.fxt) file to /tmp
+    assert_compiles('true', <<~RUBY, extra_args: ['--zjit-trace-exits'])
+      def test(object) = object.itself
+
+      # induce an exit just for good measure
+      array = []
+      test(array)
+      test(array)
+      def array.itself = :not_itself
+      test(array)
+
+      fxt_files = Dir.glob("/tmp/perfetto-\#{Process.pid}.fxt")
+      fxt_files.length == 1 && !File.empty?(fxt_files.first)
+    RUBY
   end
 
   private

zjit.c

@@ -32,98 +32,6 @@ enum zjit_struct_offsets {
     ISEQ_BODY_OFFSET_PARAM = offsetof(struct rb_iseq_constant_body, param)
 };
 
-// For a given raw_sample (frame), set the hash with the caller's
-// name, file, and line number. Return the  hash with collected frame_info.
-static void
-rb_zjit_add_frame(VALUE hash, VALUE frame)
-{
-    VALUE frame_id = PTR2NUM(frame);
-
-    if (RTEST(rb_hash_aref(hash, frame_id))) {
-        return;
-    }
-    else {
-        VALUE frame_info = rb_hash_new();
-        // Full label for the frame
-        VALUE name = rb_profile_frame_full_label(frame);
-        // Absolute path of the frame from rb_iseq_realpath
-        VALUE file = rb_profile_frame_absolute_path(frame);
-        // Line number of the frame
-        VALUE line = rb_profile_frame_first_lineno(frame);
-
-        // If absolute path isn't available use the rb_iseq_path
-        if (NIL_P(file)) {
-            file = rb_profile_frame_path(frame);
-        }
-
-        rb_hash_aset(frame_info, ID2SYM(rb_intern("name")), name);
-        rb_hash_aset(frame_info, ID2SYM(rb_intern("file")), file);
-        rb_hash_aset(frame_info, ID2SYM(rb_intern("samples")), INT2NUM(0));
-        rb_hash_aset(frame_info, ID2SYM(rb_intern("total_samples")), INT2NUM(0));
-        rb_hash_aset(frame_info, ID2SYM(rb_intern("edges")), rb_hash_new());
-        rb_hash_aset(frame_info, ID2SYM(rb_intern("lines")), rb_hash_new());
-
-        if (line != INT2FIX(0)) {
-            rb_hash_aset(frame_info, ID2SYM(rb_intern("line")), line);
-        }
-
-       rb_hash_aset(hash, frame_id, frame_info);
-    }
-}
-
-// Parses the ZjitExitLocations raw_samples and line_samples collected by
-// rb_zjit_record_exit_stack and turns them into 3 hashes (raw, lines, and frames) to
-// be used by RubyVM::ZJIT.exit_locations. zjit_raw_samples represents the raw frames information
-// (without name, file, and line), and zjit_line_samples represents the line information
-// of the iseq caller.
-VALUE
-rb_zjit_exit_locations_dict(VALUE *zjit_raw_samples, int *zjit_line_samples, int samples_len)
-{
-    VALUE result = rb_hash_new();
-    VALUE raw_samples = rb_ary_new_capa(samples_len);
-    VALUE line_samples = rb_ary_new_capa(samples_len);
-    VALUE frames = rb_hash_new();
-    int idx = 0;
-
-    // While the index is less than samples_len, parse zjit_raw_samples and
-    // zjit_line_samples, then add casted values to raw_samples and line_samples array.
-    while (idx < samples_len) {
-        int num = (int)zjit_raw_samples[idx];
-        int line_num = (int)zjit_line_samples[idx];
-        idx++;
-
-        // + 1 as we append an additional sample for the insn
-        rb_ary_push(raw_samples, SIZET2NUM(num + 1));
-        rb_ary_push(line_samples, INT2NUM(line_num + 1));
-
-        // Loop through the length of samples_len and add data to the
-        // frames hash. Also push the current value onto the raw_samples
-        // and line_samples array respectively.
-        for (int o = 0; o < num; o++) {
-            rb_zjit_add_frame(frames, zjit_raw_samples[idx]);
-            rb_ary_push(raw_samples, SIZET2NUM(zjit_raw_samples[idx]));
-            rb_ary_push(line_samples, INT2NUM(zjit_line_samples[idx]));
-            idx++;
-        }
-
-        rb_ary_push(raw_samples, SIZET2NUM(zjit_raw_samples[idx]));
-        rb_ary_push(line_samples, INT2NUM(zjit_line_samples[idx]));
-        idx++;
-
-        rb_ary_push(raw_samples, SIZET2NUM(zjit_raw_samples[idx]));
-        rb_ary_push(line_samples, INT2NUM(zjit_line_samples[idx]));
-        idx++;
-    }
-
-    // Set add the raw_samples, line_samples, and frames to the results
-    // hash.
-    rb_hash_aset(result, ID2SYM(rb_intern("raw")), raw_samples);
-    rb_hash_aset(result, ID2SYM(rb_intern("lines")), line_samples);
-    rb_hash_aset(result, ID2SYM(rb_intern("frames")), frames);
-
-    return result;
-}
-
 void rb_zjit_profile_disable(const rb_iseq_t *iseq);
 
 void

zjit.rb

@@ -16,9 +16,6 @@ module RubyVM::ZJIT
   if Primitive.rb_zjit_print_stats_p
     at_exit { print_stats }
   end
-  if Primitive.rb_zjit_trace_exit_locations_enabled_p
-    at_exit { dump_locations }
-  end
 end
 
 class << RubyVM::ZJIT
@@ -65,110 +62,6 @@ def induce_side_exit! = nil
   # Actually running this method does nothing, whether ZJIT sees the call or not.
   def induce_breakpoint! = nil
 
-  # If --zjit-trace-exits is enabled parse the hashes from
-  # Primitive.rb_zjit_get_exit_locations into a format readable
-  # by Stackprof. This will allow us to find the exact location of a
-  # side exit in ZJIT based on the instruction that is exiting.
-  def exit_locations
-    return unless trace_exit_locations_enabled?
-
-    results = Primitive.rb_zjit_get_exit_locations
-    raw_samples = results[:raw]
-    line_samples = results[:lines]
-    frames = results[:frames]
-    samples_count = 0
-
-    # Use nonexistent.def as a dummy file name.
-    frame_template = { samples: 0, total_samples: 0, edges: {}, name: name, file: "nonexistent.def", line: nil, lines: {} }
-
-    # Loop through all possible instructions and setup the frame hash.
-    RubyVM::INSTRUCTION_NAMES.each_with_index do |name, frame_id|
-      frames[frame_id] = frame_template.dup.tap { |h| h[:name] = name }
-    end
-
-    # Loop through the raw_samples and build the hashes for StackProf.
-    # The loop is based off an example in the StackProf documentation and therefore
-    # this functionality can only work with that library.
-    #
-    # Raw Samples:
-    # [ length, frame1, frame2, frameN, ..., instruction, count
-    #
-    # Line Samples
-    # [ length, line_1, line_2, line_n, ..., dummy value, count
-    i = 0
-    while i < raw_samples.length
-      stack_length = raw_samples[i]
-      i += 1 # consume the stack length
-
-      sample_count = raw_samples[i + stack_length]
-
-      prev_frame_id = nil
-      stack_length.times do |idx|
-        idx += i
-        frame_id = raw_samples[idx]
-
-        if prev_frame_id
-          prev_frame = frames[prev_frame_id]
-          prev_frame[:edges][frame_id] ||= 0
-          prev_frame[:edges][frame_id] += sample_count
-        end
-
-        frame_info = frames[frame_id]
-        frame_info[:total_samples] += sample_count
-
-        frame_info[:lines][line_samples[idx]] ||= [0, 0]
-        frame_info[:lines][line_samples[idx]][0] += sample_count
-
-        prev_frame_id = frame_id
-      end
-
-      i += stack_length # consume the stack
-
-      top_frame_id = prev_frame_id
-      top_frame_line = 1
-
-      frames[top_frame_id][:samples] += sample_count
-      frames[top_frame_id][:lines] ||= {}
-      frames[top_frame_id][:lines][top_frame_line] ||= [0, 0]
-      frames[top_frame_id][:lines][top_frame_line][1] += sample_count
-
-      samples_count += sample_count
-      i += 1
-    end
-
-    results[:samples] = samples_count
-
-    # These values are mandatory to include for stackprof, but we don't use them.
-    results[:missed_samples] = 0
-    results[:gc_samples] = 0
-    results
-  end
-
-  # Marshal dumps exit locations to the given filename.
-  #
-  # Usage:
-  #
-  # In a script call:
-  #
-  #   RubyVM::ZJIT.dump_exit_locations("my_file.dump")
-  #
-  # Then run the file with the following options:
-  #
-  #   ruby --zjit --zjit-stats --zjit-trace-exits test.rb
-  #
-  # Once the code is done running, use Stackprof to read the dump file.
-  # See Stackprof documentation for options.
-  def dump_exit_locations(filename)
-    unless trace_exit_locations_enabled?
-      raise ArgumentError, "--zjit-trace-exits must be enabled to use dump_exit_locations."
-    end
-
-    File.open(filename, "wb") do |file|
-      Marshal.dump(RubyVM::ZJIT.exit_locations, file)
-      file.size
-    end
-  end
-
   # Check if `--zjit-stats` is used
   def stats_enabled?
     Primitive.rb_zjit_stats_enabled_p
@@ -387,13 +280,4 @@ def print_stats_file
     end
   end
 
-  def dump_locations # :nodoc:
-    return unless trace_exit_locations_enabled?
-
-    filename = "zjit_exits_#{Process.pid}.dump"
-    n_bytes = dump_exit_locations(filename)
-
-    absolute_filename = File.expand_path(filename)
-    $stderr.puts("#{n_bytes} bytes written to #{absolute_filename}")
-  end
 end

zjit/bindgen/src/main.rs

@@ -299,7 +299,9 @@ fn main() {
         .allowlist_function("rb_RSTRING_PTR")
         .allowlist_function("rb_RSTRING_LEN")
         .allowlist_function("rb_ENCODING_GET")
-        .allowlist_function("rb_zjit_exit_locations_dict")
+        .allowlist_function("rb_profile_frame_full_label")
+        .allowlist_function("rb_profile_frame_absolute_path")
+        .allowlist_function("rb_profile_frame_path")
         .allowlist_function("rb_optimized_call")
         .allowlist_function("rb_jit_icache_invalidate")
         .allowlist_function("rb_zjit_print_exception")

zjit/src/backend/lir.rs

@@ -2727,7 +2727,11 @@ impl Assembler
                         // ccall doesn't clobber caller-saved registers
                         // holding stack/local operands.
                         compile_exit_save_state(self, &exit);
-                        asm_ccall!(self, rb_zjit_record_exit_stack, pc);
+                        // Leak a CString with the reason so it's available at runtime
+                        let reason_cstr = std::ffi::CString::new(reason.to_string())
+                            .unwrap_or_else(|_| std::ffi::CString::new("unknown").unwrap());
+                        let reason_ptr = reason_cstr.into_raw() as *const u8;
+                        asm_ccall!(self, rb_zjit_record_exit_stack, Opnd::const_ptr(reason_ptr));
                         compile_exit_return(self);
                     } else {
                         // If the side exit has already been compiled, jump to it.

zjit/src/codegen.rs

@@ -467,7 +467,14 @@ fn gen_function(cb: &mut CodeBlock, iseq: IseqPtr, version: IseqVersionRef, func
                     if let Err(last_snapshot) = result {
                         debug!("ZJIT: gen_function: Failed to compile insn: {insn_id} {insn}. Generating side-exit.");
                         gen_incr_counter(&mut asm, exit_counter_for_unhandled_hir_insn(&insn));
-                        gen_side_exit(&mut jit, &mut asm, &SideExitReason::UnhandledHIRInsn(insn_id), &function.frame_state(last_snapshot));
+                        let reason = match insn {
+                            Insn::ArrayMax { .. }      => SideExitReason::UnhandledHIRArrayMax,
+                            Insn::FixnumDiv { .. }     => SideExitReason::UnhandledHIRFixnumDiv,
+                            Insn::Throw { .. }         => SideExitReason::UnhandledHIRThrow,
+                            Insn::InvokeBuiltin { .. } => SideExitReason::UnhandledHIRInvokeBuiltin,
+                            _                          => SideExitReason::UnhandledHIRUnknown(insn_id),
+                        };
+                        gen_side_exit(&mut jit, &mut asm, &reason, &function.frame_state(last_snapshot));
                         // Don't bother generating code after a side-exit. We won't run it.
                         // TODO(max): Generate ud2 or equivalent.
                         break;

zjit/src/cruby.rs

@@ -902,15 +902,18 @@ pub fn iseq_get_location(iseq: IseqPtr, pos: u32) -> String {
     s
 }
 
+pub fn ruby_str_to_rust_string_result(v: VALUE) -> Result<String, std::string::FromUtf8Error> {
+    let str_ptr = unsafe { rb_RSTRING_PTR(v) } as *mut u8;
+    let str_len: usize = unsafe { rb_RSTRING_LEN(v) }.try_into().unwrap();
+    let str_slice: &[u8] = unsafe { std::slice::from_raw_parts(str_ptr, str_len) };
+    String::from_utf8(str_slice.to_vec())
+}
 
 // Convert a CRuby UTF-8-encoded RSTRING into a Rust string.
 // This should work fine on ASCII strings and anything else
 // that is considered legal UTF-8, including embedded nulls.
-fn ruby_str_to_rust_string(v: VALUE) -> String {
-    let str_ptr = unsafe { rb_RSTRING_PTR(v) } as *mut u8;
-    let str_len: usize = unsafe { rb_RSTRING_LEN(v) }.try_into().unwrap();
-    let str_slice: &[u8] = unsafe { std::slice::from_raw_parts(str_ptr, str_len) };
-    String::from_utf8(str_slice.to_vec()).unwrap_or_default()
+pub fn ruby_str_to_rust_string(v: VALUE) -> String {
+    ruby_str_to_rust_string_result(v).unwrap_or_default()
 }
 
 pub fn ruby_sym_to_rust_string(v: VALUE) -> String {

zjit/src/cruby_bindings.inc.rs

@@ -5,7 +5,6 @@ use std::{ffi::c_void, ops::Range};
 use crate::{cruby::*, state::ZJITState, stats::with_time_stat, virtualmem::CodePtr};
 use crate::payload::{IseqPayload, IseqVersionRef, get_or_create_iseq_payload};
 use crate::stats::Counter::gc_time_ns;
-use crate::state::gc_mark_raw_samples;
 
 /// GC callback for marking GC objects in the per-ISEQ payload.
 #[unsafe(no_mangle)]
@@ -207,5 +206,5 @@ fn ranges_overlap<T>(left: &Range<T>, right: &Range<T>) -> bool where T: Partial
 /// Callback for marking GC objects inside [crate::invariants::Invariants].
 #[unsafe(no_mangle)]
 pub extern "C" fn rb_zjit_root_mark() {
-    gc_mark_raw_samples();
+    // TODO(max): Either add roots to mark or consider removing this callback
 }

zjit/src/gc.rs

@@ -498,7 +498,11 @@ pub enum SideExitReason {
     UnhandledNewarraySend(vm_opt_newarray_send_type),
     UnhandledDuparraySend(u64),
     UnknownSpecialVariable(u64),
-    UnhandledHIRInsn(InsnId),
+    UnhandledHIRArrayMax,
+    UnhandledHIRFixnumDiv,
+    UnhandledHIRThrow,
+    UnhandledHIRInvokeBuiltin,
+    UnhandledHIRUnknown(InsnId),
     UnhandledYARVInsn(u32),
     UnhandledCallType(CallType),
     UnhandledBlockArg,