ruby-prof 2.0.4 → 2.0.5

data/docs/architecture.md

@@ -1,304 +0,0 @@
-# Architecture
-
-## Overview
-
-ruby-prof is a C extension that uses Ruby's [TracePoint](https://docs.ruby-lang.org/en/master/TracePoint.html) API to intercept method calls and returns. Every time a method is entered or exited, ruby-prof records timing and (optionally) allocation data. This tracing approach means ruby-prof captures every method invocation, giving exact call counts and complete call graphs.
-
-The diagram below shows the main classes that make up ruby-prof:
-
-```mermaid
-classDiagram
-    Profile "1" *-- "1" Measurer
-    Profile "1" *-- "*" Thread
-    Thread "1" *-- "1" Stack
-    Thread "1" *-- "*" MethodInfo
-    Thread "1" *-- "1" CallTree
-    Stack "1" o-- "*" Frame
-    Frame --> CallTree
-    CallTree "1" *-- "1" Measurement
-    CallTree --> MethodInfo : target
-    MethodInfo "1" *-- "1" CallTrees
-    MethodInfo "1" *-- "1" Measurement
-    MethodInfo "1" *-- "*" Allocation
-    CallTrees o-- "*" CallTree
-
-    class Profile {
-        +threads: Hash
-        +measurer: Measurer
-    }
-    class Measurer {
-        +mode: MeasurerMode
-        +track_allocations: boolean
-        +multiplier: double
-        +measure: function pointer
-    }
-    class Thread {
-        +methods: Hash
-        +stack: Stack
-        +callTree: CallTree
-    }
-    class Stack {
-        +frames: Array
-    }
-    class Frame {
-        +callTree: CallTree
-    }
-    class CallTree {
-        +parent: CallTree
-        +children: Hash
-        +target: MethodInfo
-        +measurement: Measurement
-    }
-    class MethodInfo {
-        +allocations: Hash
-        +callTrees: CallTrees
-        +measurement: Measurement
-    }
-    class Measurement {
-        +total_time: double
-        +self_time: double
-        +wait_time: double
-        +called: integer
-    }
-    class Allocation {
-        +count: integer
-        +source_file: string
-        +source_line: int
-        +klass: VALUE
-    }
-    class CallTrees {
-        +callTrees: Array
-    }
-```
-
-## Profile
-
-Profile is the top-level object returned by a profiling run:
-
-```ruby
-profile = RubyProf::Profile.profile do
-  ...
-end
-```
-
-A Profile owns a Measurer that determines what is being measured, and a collection of Threads representing each thread (or fiber) that was active during profiling.
-
-## Measurer and Measurement
-
-The **Measurer** controls what ruby-prof measures. It holds a function pointer that is called on every method entry and exit to take a measurement. The three modes are:
-
-- **Wall time** — elapsed real time
-- **Process time** — CPU time consumed by the process (excludes time spent in sleep or I/O)
-- **Allocations** — number of objects allocated
-
-Each CallTree and MethodInfo holds a **Measurement** that accumulates the results: total time, self time (excluding children), wait time (time spent waiting on other threads), and call count.
-
-## Thread
-
-Each Thread tracks the methods called on that thread and owns the root of a call tree. It also maintains an internal Stack of Frames used during profiling to track the current call depth.
-
-**Stack** and **Frame** are transient — they exist only while profiling is active. A Frame records timing data for a single method invocation on the stack, including start time and time spent in child calls. When a method returns, its Frame is popped and the accumulated timing is transferred to the corresponding CallTree node.
-
-## CallTree and MethodInfo
-
-These two classes are central to ruby-prof and represent two different views of the same profiling data:
-
-- **CallTree** records the calling structure — which method called which, forming a tree. Each node has a parent, children, and a reference to its target MethodInfo. A method that is called from two different call sites will have two separate CallTree nodes, each with its own Measurement. Recursive methods are handled by creating a chain of CallTree nodes (see [Recursion](#recursion) below).
-
-- **MethodInfo** represents a single method regardless of where it was called from. It aggregates data across all call sites. Each MethodInfo holds a CallTrees collection that links back to every CallTree node that invoked that method, providing both caller and callee information.
-
-This separation is what allows ruby-prof to generate both call graph reports (which show calling relationships) and flat reports (which show per-method totals).
-
-## Building the Call Tree
-
-This section describes how the call tree is constructed during profiling.
-
-Consider profiling this code:
-
-```ruby
-def process
-  validate
-  save
-end
-
-def save
-  validate
-  write
-end
-```
-
-The resulting CallTree looks like:
-
-```mermaid
-graph TD
-    A{{"[global]"}} -->|child| B{{"process"}}
-    B -->|child| C{{"validate"}}
-    B -->|child| D{{"save"}}
-    D -->|child| E{{"validate"}}
-    D -->|child| F{{"write"}}
-
-    B -.->|parent| A
-    C -.->|parent| B
-    D -.->|parent| B
-    E -.->|parent| D
-    F -.->|parent| D
-```
-
-Notice that `validate` appears as two separate CallTree nodes — one under `process` and one under `save` — because it was called from two different call sites. Each has its own parent and its own Measurement. Both nodes reference the same `validate` MethodInfo, which aggregates the data across both call sites.
-
-The following diagram shows both views together. CallTree nodes (hexagons) reference their target MethodInfo (rectangles) via dashed arrows:
-
-```mermaid
-graph TD
-    classDef calltree fill:#E8F4FD,stroke:#2E86C1
-    classDef methodinfo fill:#FADBD8,stroke:#E74C3C
-
-    CT1{{"[global]"}}:::calltree --> CT2{{"process"}}:::calltree
-    CT2 --> CT3{{"validate"}}:::calltree
-    CT2 --> CT4{{"save"}}:::calltree
-    CT4 --> CT5{{"validate"}}:::calltree
-    CT4 --> CT6{{"write"}}:::calltree
-
-    CT1 -.->|target| M1["[global]"]:::methodinfo
-    CT2 -.->|target| M2["process"]:::methodinfo
-    CT3 -.->|target| M3["validate"]:::methodinfo
-    CT4 -.->|target| M4["save"]:::methodinfo
-    CT5 -.->|target| M3
-    CT6 -.->|target| M5["write"]:::methodinfo
-
-    M3 -.->|call_trees| CT3
-    M3 -.->|call_trees| CT5
-```
-
-Both `validate` CallTree nodes point to the same `validate` MethodInfo via `target`. The MethodInfo points back to its CallTree nodes via `call_trees` — a flat array of every CallTree node that invoked this method. From this array, `callers` and `callees` are derived: `callers` walks each node's parent, and `callees` walks each node's children. Both are aggregated by method to produce a single entry per caller or callee method.
-
-### Parents
-
-Each CallTree node has exactly one parent, set at creation. When a method call event fires, the profiler determines the parent from the current frame on the stack:
-
-```c
-parent_call_tree = frame->call_tree;
-```
-
-The parent is the CallTree node that was active (top of the stack) when this method was called. The root CallTree node for each thread has no parent.
-
-### Children
-
-A CallTree node's children are stored in a hash table keyed by method. The profiler looks up the method in the current parent's children. If a child already exists for that method, the existing CallTree node is **reused** and its `called` count increments. Otherwise a new node is created:
-
-```c
-call_tree = call_tree_table_lookup(parent_call_tree->children, method->key);
-
-if (!call_tree)
-{
-    call_tree = prof_call_tree_create(method, parent_call_tree, ...);
-    prof_call_tree_add_child(parent_call_tree, call_tree);
-}
-```
-
-This means each parent has **one** child CallTree per method. For example, if `foo` calls `bar` ten times, there is a single `bar` CallTree node under `foo` with `called: 10`.
-
-## Allocation
-
-When allocation tracking is enabled, each MethodInfo records the objects it allocated. An Allocation tracks the class of object created, the source location, and the count.
-
-## Memory Management
-
-The Profile object is responsible for managing the memory of its child objects, which are C structures. When a Profile is garbage collected, it recursively frees all its objects. In the class diagram, composition relationships (filled diamond) indicate ownership — a Profile frees its Threads, Threads free their CallTrees and MethodInfo instances, and so on.
-
-ruby-prof keeps a Profile alive as long as there are live references to any of its MethodInfo or CallTree objects. This is done via Ruby's GC mark phase: CallTree instances mark their associated MethodInfo, and MethodInfo instances mark their owning Profile.
-
-Starting with version 1.5, it is possible to create Thread, CallTree and MethodInfo instances from Ruby (this was added to support testing). These Ruby-created objects are owned by Ruby's garbage collector rather than the C extension. An internal ownership flag on each instance tracks who is responsible for freeing it.
-
-## Recursion
-
-The call tree handles recursion naturally — each recursive call has a different parent, so new nodes are created at each level just like any other method call. The only special handling is in timing calculation, where care is needed to avoid double-counting.
-
-### How Recursive Calls Create New Nodes
-
-Consider a simple recursive method:
-
-```ruby
-def simple(n)
-  sleep(1)
-  return if n == 0
-  simple(n - 1)
-end
-
-simple(2)
-```
-
-Each recursive call to `simple` has a different parent CallTree node, so the lookup in the parent's children misses and a new node is created at each level:
-
-```mermaid
-graph TD
-    classDef calltree fill:#E8F4FD,stroke:#2E86C1
-    classDef methodinfo fill:#FADBD8,stroke:#E74C3C
-
-    A{{"[global]"}}:::calltree --> B{{"simple"}}:::calltree
-    B --> C{{"sleep"}}:::calltree
-    B --> D{{"simple"}}:::calltree
-    D --> E{{"sleep"}}:::calltree
-    D --> F{{"simple"}}:::calltree
-    F --> G{{"sleep"}}:::calltree
-
-    B -.-> A
-    C -.-> B
-    D -.-> B
-    E -.-> D
-    F -.-> D
-    G -.-> F
-
-    B -.-> M["simple"]:::methodinfo
-    D -.-> M
-    F -.-> M
-```
-
-The CallTree is always acyclic — each recursive call creates a new node at a deeper level. However, there is a single `simple` MethodInfo (red rectangle at the bottom of the diagram), and each CallTree node points to it.
-
-### The Visits Counter
-
-Both CallTree and MethodInfo have a `visits` field that tracks how many times that node or method is currently on the stack. This counter is incremented on method entry and decremented on method exit:
-
-```c
-// Method entry (prof_frame_push):
-call_tree->visits++;
-if (call_tree->method->visits > 0)
-    call_tree->method->recursive = true;
-call_tree->method->visits++;
-
-// Method exit (prof_frame_pop):
-call_tree->visits--;
-call_tree->method->visits--;
-```
-
-The MethodInfo `visits` counter serves two purposes:
-
-1. Detecting recursion — if `method->visits > 0` when a method is entered, the method is currently an ancestor of itself in the call stack and is marked recursive.
-
-2. Correct total_time accounting — total time is only added to the Measurement when a node's `visits` drops back to 1, meaning it is the outermost invocation:
-
-```c
-// Only accumulate total_time at the outermost visit
-if (call_tree->visits == 1)
-    call_tree->measurement->total_time += total_time;
-
-if (call_tree->method->visits == 1)
-    call_tree->method->measurement->total_time += total_time;
-```
-
-Without this guard, total time would be double-counted. Consider `simple(2)` with 1-second sleeps. The outermost call takes ~3 seconds total, the middle call ~2 seconds, and the innermost ~1 second. Naively summing all three would give 6 seconds, but the actual elapsed time is only 3 seconds. By only recording total_time at the outermost visit, the MethodInfo correctly reports 3 seconds.
-
-### Recursion at the MethodInfo Level
-
-At the MethodInfo level, recursive methods create cycles. A recursive `simple` method has itself as both a caller and a callee:
-
-```mermaid
-graph TD
-    classDef methodinfo fill:#FADBD8,stroke:#E74C3C
-    A["global"]:::methodinfo -->|"calls"| B["simple"]:::methodinfo
-    B -->|"calls"| C["sleep"]:::methodinfo
-    B -->|"calls"| B
-```
-
-This is why MethodInfo has a `recursive?` flag — printers that operate on MethodInfo (such as the graph printer) need to be aware of these cycles. However, the underlying CallTree structure is always a tree with no structural cycles.

data/docs/best-practices.md

@@ -1,27 +0,0 @@
-# Best Practices
-
-Profiling gives you amazing insight into your program. What you think is slow is almost never what is actually slow. Below are some best practices to help unlock this power.
-
-## Start With Realistic Runs
-
-When profiling data-heavy work, start with a smaller sample of the data instead of the full dataset. Profile a portion first (for example 1% or 10%). It is faster, easier to understand, and often enough to find the main bottleneck. Once you have a likely fix, validate it with a larger and more realistic workload so you know the result still holds in context. Run the same profile more than once and warm up before you measure so one-time startup work does not dominate the report.
-
-## Choose The Right Measurement Mode
-
-Pick the measurement mode based on the question you are asking. Use `WALL_TIME` for end-to-end latency, `PROCESS_TIME` for CPU-focused work, and `ALLOCATIONS` when object churn is the concern. See [Measurement Mode](advanced-usage.md#measurement-mode) for details.
-
-## Reduce Noise Before Deep Analysis
-
-When framework internals or concurrency noise dominate output, narrow the scope first. Use `exclude_common` or explicit method exclusions, and use thread filtering (`include_threads` / `exclude_threads`) when needed. For highly concurrent workloads, merging worker results (`merge!` or Rack `merge_fibers: true`) can make trends much easier to read. See [Profiling Options](advanced-usage.md#profiling-options), [Method Exclusion](advanced-usage.md#method-exclusion), and [Merging Threads and Fibers](advanced-usage.md#merging-threads-and-fibers).
-
-## Use Reports In A Sequence
-
-Start with a quick summary, then drill down. In practice, this usually means using `FlatPrinter` to find hotspots, `GraphHtmlPrinter` (or `GraphPrinter`) to understand caller/callee relationships, and `FlameGraphPrinter` to validate dominant paths visually. See [Reports](reports.md), especially [Creating Reports](reports.md#creating-reports) and [Report Types](reports.md#report-types).
-
-## Use Threshold Filters Early
-
-Threshold filters are one of the fastest ways to make a large profile readable. Start with `min_percent` to hide low-impact methods in most printers. For `GraphHtmlPrinter`, use `min_time` when you want to drop methods below an absolute time cutoff. These filters help you focus on the code that actually moves total runtime.
-
-## Compare Trends, Not Single Snapshots
-
-Do not optimize based on one run unless the signal is overwhelming. Compare before/after profiles under the same workload, then prioritize repeated hot paths over one-off spikes.

data/docs/getting-started.md

@@ -1,130 +0,0 @@
-# Getting Started
-
-There are three ways to use ruby-prof:
-
-- command line
-- convenience API
-- core API
-
-## Command Line
-
-The easiest way to use ruby-prof is via the command line, which requires no modifications to your program. The basic usage is:
-
-```
-ruby-prof [options] <script.rb> [--] [script-options]
-```
-
-Where script.rb is the program you want to profile.
-
-For a full list of options, see the RubyProf::Cmd documentation or execute the following command:
-
-```
-ruby-prof -h
-```
-
-## Convenience API
-
-The second way to use ruby-prof is via its convenience API. This requires small modifications to the program you want to profile:
-
-```ruby
-require 'ruby-prof'
-
-profile = RubyProf::Profile.new
-
-# profile the code
-profile.start
-# ... code to profile ...
-result = profile.stop
-
-# print a flat profile to text
-printer = RubyProf::FlatPrinter.new(result)
-printer.print(STDOUT)
-```
-
-Alternatively, you can use a block to tell ruby-prof what to profile:
-
-```ruby
-require 'ruby-prof'
-
-# profile the code
-result = RubyProf::Profile.profile do
-  # ... code to profile ...
-end
-
-# print a graph profile to text
-printer = RubyProf::GraphPrinter.new(result)
-printer.print(STDOUT)
-```
-
-ruby-prof also supports pausing and resuming profiling runs.
-
-```ruby
-require 'ruby-prof'
-
-profile = RubyProf::Profile.new
-
-# profile the code
-profile.start
-# ... code to profile ...
-
-profile.pause
-# ... other code ...
-
-profile.resume
-# ... code to profile ...
-
-result = profile.stop
-```
-
-Note that resume will only work if start has been called previously. In addition, resume can also take a block:
-
-```ruby
-require 'ruby-prof'
-
-profile = RubyProf::Profile.new
-
-# profile the code
-profile.start
-# ... code to profile ...
-
-profile.pause
-# ... other code ...
-
-profile.resume do
-  # ... code to profile...
-end
-
-result = profile.stop
-```
-
-With this usage, resume will automatically call pause at the end of the block.
-
-The `RubyProf::Profile.profile` method can take various options, which are described in [Profiling Options](advanced-usage.md#profiling-options).
-
-## Core API
-
-The convenience API is a wrapper around the `RubyProf::Profile` class. Using the Profile class directly provides additional functionality, such as [method exclusion](advanced-usage.md#method-exclusion).
-
-To create a new profile:
-
-```ruby
-require 'ruby-prof'
-
-profile = RubyProf::Profile.new(measure_mode: RubyProf::WALL_TIME)
-result = profile.profile do
-           ...
-         end
-```
-
-Once a profile is completed, you can either generate a [report](reports.md) via a printer or [save](advanced-usage.md#saving-results) the results for later analysis. For a list of profiling options, please see the [Profiling Options](advanced-usage.md#profiling-options) section.
-If you are unsure which report to generate first, see [Report Types](reports.md#report-types).
-
-
-However, using ruby-prof also comes with two caveats:
-
-- To use ruby-prof you generally need to include a few lines of extra code in your program (although see [command line usage](getting-started.md#command-line))
-- Using ruby-prof will cause your program to run slower (see [Performance](index.md#performance) section)
-
-Most of the time, these two caveats are acceptable. But if you need to determine why a program running in production is slow or hung, a sampling profiler will be a better choice. Excellent choices include [stackprof](https://github.com/tmm1/stackprof) or [rbspy](https://rbspy.github.io/).
-
-If you are just interested in memory usage, you may also want to checkout the [memory_profiler](https://github.com/SamSaffron/memory_profiler) gem (although ruby-prof provides similar information).

data/docs/history.md

@@ -1,11 +0,0 @@
-# History
-
-For a full list of changes between versions, see the [Changelog](changelog.md).
-
-The first version of ruby-prof, 0.1.1, was released on March 22, 2005 by [Shugo Maeda](https://shugo.net/) The original [source](https://shugo.net/archive/ruby-prof/) code is still available on his website (it is not actually in the git history). ruby-prof was a vast improvement at the time, running 30 times faster as the original ruby profiler.
-
-Version [0.4.0](https://rubygems.org/gems/ruby-prof/versions/0.4.0) was the first version packaged as a Ruby gem. Version 0.4.0 also introduced Windows support, thread support and added a number of additional reports such as the graph report in HTML and the call graph report.
-
-A number of versions were subsequently released, with a 1.0.0 [release](https://cfis.savagexi.com/2019/07/29/ruby-prof-1-0/) finally happening in July of 2019. Version 1.0.0 was a major rewrite that significantly improved performance, correctly profiled recursive methods, redesigned reports, added allocation/memory measurement support and introduced saving and reloading profiling results. Since then ruby-prof has continued to evolve along with Ruby with 19 releases.
-
-Version 2.0.0 will mark the 20th release of ruby-prof since the 1.0.0 release. Version 2.0.0 supports Ruby 4 and includes new flame/icicle graph support, revamped reports and improved documentation. The reason for the 2.0.0 jump is because profiling memory sizes has been removed due to changes in Ruby 4.0.0. In addition, the old compatibility API was also removed.

data/docs/index.md

@@ -1,45 +0,0 @@
-# ruby-prof
-
-ruby-prof is a [tracing](./alternatives.md#tracing-vs-sampling) profiler for MRI Ruby with a long [history](./history.md) that dates back to 2005! Its features include:
-
-- Measurement Modes - ruby-prof can measure program [wall time](advanced-usage.md#wall-time), [process time](advanced-usage.md#process-time) and [object allocations](advanced-usage.md#object-allocations).
-- Reports - ruby-prof can generate [flat](reports.md#flat), [graph (text)](reports.md#graph-text), [graph (HTML)](reports.md#graph-html), [flame graph](reports.md#flame-graph), [call stack](reports.md#call-stack), [graphviz](reports.md#graphviz), [cachegrind](reports.md#cachegrind), and [call info](reports.md#call-info-report) reports.
-- Threads - supports profiling multiple threads simultaneously.
-- Fibers - supports profiling multiple fibers simultaneously.
-- Merging - supports merging results across fibers or threads
-- Recursive - supports profiling recursive methods
-
-![Flame Graph](../public/images/flame_graph.png)
-
-## Why ruby-prof?
-
-ruby-prof is helpful if your program is slow and you want to know why! It can help you track down methods that are either slow or allocate a large number of objects. Often times the results will surprise you - when profiling what you think you know almost always turns out to be wrong.
-
-## Installation
-To install ruby-prof:
-
-```
-gem install ruby-prof
-```
-
-If you are running Linux or Unix you'll need to have a C compiler installed so the extension can be built when it is installed. If you are running Windows, then you should install the Windows specific gem or install [devkit](https://rubyinstaller.org/add-ons/devkit.html).
-
-ruby-prof requires Ruby 3.2.0 or higher. If you need to work with older Ruby versions then you can download an older version of ruby-prof.
-
-## Performance
-ruby-prof is a tracing profiler, not a sampling profiler, and thus will cause your program to run slower. Our tests show that the overhead varies considerably based on the code being profiled. Significant effort has been put into reducing this overhead, but most programs will run approximately twice as slow while highly recursive programs (like the fibonacci series test) may run up to five times slower.
-
-## History
-ruby-prof has been under continuous development since 2005 — see the full [History](history.md) page.
-
-## API Documentation
-
-API documentation for each class is available at the [ruby-prof API docs](https://ruby-prof.github.io/doc/index.html).
-
-## License
-
-See [LICENSE](../LICENSE) for license information.
-
-## Development
-
-Code is located at [github.com/ruby-prof/ruby-prof](https://github.com/ruby-prof/ruby-prof).

data/docs/profiling-rails.md

@@ -1,64 +0,0 @@
-# Profiling Rails
-
-To profile a Rails application it is vital to run it using production-like settings (cache classes, cache view lookups, etc.). Otherwise, Rails dependency loading code will overwhelm any time spent in the application itself (our tests show that Rails dependency loading causes a roughly 6x slowdown). The best way to do this is to create a new Rails environment, `profile`.
-
-To profile Rails:
-
-1. Add ruby-prof to your Gemfile:
-
-   ```ruby
-   group :profile do
-     gem 'ruby-prof'
-   end
-   ```
-
-   Then install it:
-
-   ```bash
-   bundle install
-   ```
-
-2. Create `config/environments/profile.rb` with production-like settings and the ruby-prof middleware:
-
-   ```ruby
-   # config/environments/profile.rb
-   require_relative "production"
-
-   Rails.application.configure do
-     # Optional: reduce noise while profiling.
-     config.log_level = :warn
-
-     # Optional: disable controller/view caching if you want raw app execution timing.
-     config.action_controller.perform_caching = false
-
-     config.middleware.use Rack::RubyProf, path: Rails.root.join("tmp/profile")
-   end
-   ```
-
-   By default the rack adapter generates flat text, graph text, graph HTML, and call stack HTML reports.
-
-3. Start Rails in the profile environment:
-
-   ```bash
-   bin/rails server -e profile
-   ```
-
-   You can run a console in the same environment with:
-
-   ```bash
-   bin/rails console -e profile
-   ```
-
-4. Make a request to generate profile output:
-
-   ```bash
-   curl http://127.0.0.1:3000/
-   ```
-
-5. Inspect reports in `tmp/profile`:
-
-   ```bash
-   ls -1 tmp/profile
-   ```
-
-   Reports are generated per request path. Repeating the same request path overwrites the previous report files for that path.

data/docs/public/examples/example.rb

@@ -1,33 +0,0 @@
-# A small synthetic workload for demonstrating ruby-prof reports.
-# word_freq.rb
-
-def normalize(text)
-  text.downcase.gsub(/[^a-z\s]/, "")
-end
-
-def tokenize(text)
-  text.split(/\s+/)
-end
-
-def count_words(words)
-  counts = Hash.new(0)
-  words.each { |w| counts[w] += 1 }
-  counts
-end
-
-def top_words(counts, n = 10)
-  counts.sort_by { |_, v| -v }.take(n)
-end
-
-def run_example
-  text = <<~EOS * 200
-  Ruby is a dynamic, open source programming language with a focus on
-  simplicity and productivity. It has an elegant syntax that is natural
-  to read and easy to write.
-EOS
-
-  normalized = normalize(text)
-  tokens     = tokenize(normalized)
-  counts     = count_words(tokens)
-  top        = top_words(counts)
-end