From 33cd97006d740211e915ca85a42ffcb55e76919c Mon Sep 17 00:00:00 2001
From: Stan Lo <stan.lo@shopify.com>
Date: Wed, 10 Sep 2025 16:57:52 +0100
Subject: [DOC] ZJIT: Add a section for stats (#14497)

---
 doc/zjit.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/doc/zjit.md b/doc/zjit.md
index b5b605d5cb..4eedcca3ba 100644
--- a/doc/zjit.md
+++ b/doc/zjit.md
@@ -110,6 +110,49 @@ You can also run a single test case by matching the method name:
 make test-all TESTS="test/ruby/test_zjit.rb -n TestZJIT#test_putobject"
 ```
 
+## Statistics Collection
+
+ZJIT provides detailed statistics about JIT compilation and execution behavior.
+
+### Basic Stats
+
+Run with basic statistics printed on exit:
+
+```bash
+./miniruby --zjit-stats script.rb
+```
+
+Collect stats without printing (access via `RubyVM::ZJIT.stats` in Ruby):
+
+```bash
+./miniruby --zjit-stats=quiet script.rb
+```
+
+### Accessing Stats in Ruby
+
+```ruby
+# Check if stats are enabled
+if RubyVM::ZJIT.stats_enabled?
+  stats = RubyVM::ZJIT.stats
+  puts "Compiled ISEQs: #{stats[:compiled_iseq_count]}"
+  puts "Failed ISEQs: #{stats[:failed_iseq_count]}"
+
+  # You can also reset stats during execution
+  RubyVM::ZJIT.reset_stats!
+end
+```
+
+### Performance Ratio
+
+The `ratio_in_zjit` stat shows the percentage of Ruby instructions executed in JIT code vs interpreter. This metric only appears when ZJIT is built with `--enable-zjit=stats` (which enables `rb_vm_insn_count` tracking) and represents a key performance indicator for ZJIT effectiveness.
+
+To build with stats support:
+
+```bash
+./configure --enable-zjit=stats
+make -j
+```
+
 ## ZJIT Glossary
 
 This glossary contains terms that are helpful for understanding ZJIT.
-- 
cgit v1.2.3