ruby-prof 1.7.2 → 2.0.0

data/docs/advanced-usage.md

@@ -0,0 +1,132 @@
+# Advanced Usage
+
+This section describes advanced usage of ruby-prof. Additional documentation for every class is also [available](index.md#api-documentation). For workflow guidance, see [Best Practices](best-practices.md).
+
+## Profiling Options
+
+ruby-prof understands the following options when profiling code:
+
+**measure_mode** - What ruby-prof should measure. For more information see the [Measurement Mode](#measurement-mode) section.
+
+**track_allocations** - Tracks each object location, including the object class and source file location. For more information see the [Allocation Tracking](#allocation-tracking) section.
+
+**exclude_threads** - Array of threads which should not be profiled. For more information see the [Thread Inclusion/Exclusion](#thread-inclusionexclusion) section.
+
+**include_threads** - Array of threads which should be profiled. All other threads will be ignored. For more information see the [Thread Inclusion/Exclusion](#thread-inclusionexclusion) section.
+
+**allow_exceptions** - Whether to raise exceptions encountered during profiling, or to suppress them. Defaults to false.
+
+**exclude_common** - Automatically calls `exclude_common_methods!` to exclude commonly cluttering methods. Defaults to false. For more information see the [Method Exclusion](#method-exclusion) section.
+
+## Measurement Mode
+
+The measurement mode determines what ruby-prof measures when profiling code. Supported measurements are:
+
+### Wall Time
+
+Wall time measures the real-world time elapsed between any two moments in seconds. If there are other processes concurrently running on the system that use significant CPU or disk time during a profiling run then the reported results will be larger than expected. On Windows, wall time is measured using `QueryPerformanceCounter` and on other platforms by `clock_gettime(CLOCK_MONOTONIC)`. Use `RubyProf::WALL_TIME` to select this mode.
+
+### Process Time
+
+Process time measures the time used by a process between any two moments in seconds. It is unaffected by other processes concurrently running on the system. Remember with process time that calls to methods like sleep will not be included in profiling results. On Windows, process time is measured using `GetProcessTimes` and on other platforms by `clock_gettime`. Use `RubyProf::PROCESS_TIME` to select this mode.
+
+### Object Allocations
+
+Object allocations measures how many objects each method in a program allocates. Measurements are done via Ruby's `RUBY_INTERNAL_EVENT_NEWOBJ` trace event, counting each new object created (excluding internal `T_IMEMO` objects). Use `RubyProf::ALLOCATIONS` to select this mode.
+
+To set the measurement mode:
+
+```ruby
+profile = RubyProf::Profile.new(measure_mode: RubyProf::WALL_TIME)
+profile = RubyProf::Profile.new(measure_mode: RubyProf::PROCESS_TIME)
+profile = RubyProf::Profile.new(measure_mode: RubyProf::ALLOCATIONS)
+```
+
+The default value is `RubyProf::WALL_TIME`. You may also specify the measure mode by using the `RUBY_PROF_MEASURE_MODE` environment variable:
+
+```
+export RUBY_PROF_MEASURE_MODE=wall
+export RUBY_PROF_MEASURE_MODE=process
+export RUBY_PROF_MEASURE_MODE=allocations
+```
+
+## Allocation Tracking
+
+ruby-prof also has the ability to track object allocations. This functionality can be turned on via the track_allocations option:
+
+```ruby
+require 'ruby-prof'
+
+RubyProf::Profile.profile(track_allocations: true) do
+  ...
+end
+```
+
+Note the `RubyProf::ALLOCATIONS` measure mode is slightly different than tracking allocations. The measurement mode provides high level information about the number of allocations performed in each method. In contrast, tracking allocations provides detailed information about allocation type, count, and source location. Currently, to see allocations results you must use the `RubyProf::GraphHtmlPrinter`.
+
+## Thread Inclusion/Exclusion
+
+ruby-prof can profile multiple threads. Sometimes this can be overwhelming. For example, assume you want to determine why your tests are running slowly. If you are using minitest, it can run tests in parallel by spawning worker threads (to force a single worker, set `N=0` when running tests). Thus, ruby-prof provides two options to specify which threads should be profiled:
+
+**exclude_threads** - Array of threads which should not be profiled.
+
+**include_threads** - Array of threads which should be profiled. All other threads will be ignored.
+
+## Method Exclusion
+
+ruby-prof supports excluding specific methods and threads from profiling results. This is useful for reducing connectivity in the call graph, making it easier to identify the source of performance problems when using a graph printer. For example, consider `Integer#times`: it's hardly ever useful to know how much time is spent in the method itself. We are more interested in how much the passed in block contributes to the time spent in the method which contains the `Integer#times` call. The effect on collected metrics are identical to eliminating methods from the profiling result in a post process step.
+
+```ruby
+profile = RubyProf::Profile.new(...)
+profile.exclude_methods!(Integer, :times, ...)
+profile.start
+```
+
+A convenience method is provided to exclude a large number of methods which usually clutter up profiles:
+
+```ruby
+profile.exclude_common_methods!
+```
+
+However, this is a somewhat opinionated method collection. It's usually better to view it as an inspiration instead of using it directly (see [exclude_common_methods.rb](https://github.com/ruby-prof/ruby-prof/blob/e087b7d7ca11eecf1717d95a5c5fea1e36ea3136/lib/ruby-prof/profile/exclude_common_methods.rb)).
+
+## Merging Threads and Fibers
+
+ruby-prof profiles each thread and fiber separately. A common design pattern is to have a main thread delegate work to background threads or fibers. Examples include web servers such as Puma and Falcon, as well as code that uses `Enumerator`, `Fiber.new`, or async libraries.
+
+Understanding profiling results can be very difficult when there are many threads or fibers because each one appears as a separate entry in the output. To help with this, ruby-prof includes the ability to merge results for threads and fibers that start with the same root method. In the best case, this can collapse results into just two entries - one for the parent thread and one for all workers.
+
+Note the collapsed results show the sum of times for all merged threads/fibers. For example, assume there are 10 worker fibers that each took 5 seconds to run. The single merged entry will show a total time of 50 seconds.
+
+To merge threads and fibers:
+
+```ruby
+profile = RubyProf::Profile.profile do
+            ...
+          end
+profile.merge!
+```
+
+This is also supported in the Rack adapter via the `merge_fibers` option:
+
+```ruby
+config.middleware.use Rack::RubyProf, path: Rails.root.join("tmp/profile"), merge_fibers: true
+```
+
+## Saving Results
+
+It can be helpful to save the results of a profiling run for later analysis. Results can be saved using Ruby's [marshal](https://docs.ruby-lang.org/en/master/Marshal.html) library.
+
+```ruby
+profile_1 = RubyProf::Profile.profile do
+  ...
+end
+
+# Save the results
+data = Marshal.dump(profile_1)
+
+# Sometime later load the results
+profile_2 = Marshal.load(data)
+```
+
+**!!!WARNING!!!** - Only load ruby-prof profiles that you know are safe. Demarshaling data can lead to arbitrary code execution and thus can be [dangerous](https://docs.ruby-lang.org/en/master/Marshal.html#module-Marshal-label-Security+considerations).

data/docs/alternatives.md

@@ -0,0 +1,98 @@
+# Comparison with Other Profilers
+
+Ruby has several excellent profiling tools, each with different strengths. This page compares ruby-prof with three popular alternatives to help you choose the right tool for your needs.
+
+## Tracing vs Sampling
+
+The most important distinction between profilers is **tracing** vs **sampling**:
+
+- **Tracing profilers** (ruby-prof) instrument every method call and return. This provides exact call counts and complete call graphs, but adds overhead to every method invocation.
+- **Sampling profilers** (stackprof, rbspy, vernier) periodically capture stack snapshots. This has much lower overhead but may miss short-lived method calls.
+
+## Overview
+
+The table below compares ruby-prof with [stackprof](https://github.com/tmm1/stackprof), [rbspy](https://github.com/rbspy/rbspy), and [vernier](https://github.com/jhawthorn/vernier) — the three most popular sampling profilers for Ruby.
+
+| | ruby-prof | stackprof | rbspy | vernier |
+|---|---|---|---|---|
+| **Type** | Tracing | Sampling | Sampling | Sampling |
+| **Implementation** | C extension (TracePoint API) | C extension (signals) | External Rust binary | C extension (signals) |
+| **Code changes** | None ([CLI](getting-started.md#command-line)) or minimal | Minimal | None | Minimal |
+| **Ruby versions** | All, since 2006 (currently 3.2+) | 2.2+ | 1.9.3+ | 3.2.1+ |
+| **OS support** | Linux, macOS, Windows | Linux | Linux, macOS, Windows, FreeBSD | Linux, macOS |
+
+## Measurement Capabilities
+
+| | ruby-prof | stackprof | rbspy | vernier |
+|---|---|---|---|---|
+| **Wall time** | Yes | Yes | Yes | Yes |
+| **CPU/Process time** | Yes | Yes | No | No |
+| **Allocations** | Yes | Yes | No | Yes |
+| **GVL visibility** | No | No | No | Yes |
+| **GC pauses** | No | No | No | Yes |
+| **Retained memory** | No | No | No | Yes |
+| **Multi-thread** | Yes | No | No | Yes |
+| **Fibers** | Yes | No | No | No |
+
+## Report Formats
+
+| | ruby-prof | stackprof | rbspy | vernier |
+|---|---|---|---|---|
+| **Flat/Summary** | Yes | Yes | Yes | No |
+| **Call graph** | Yes (text + HTML) | No | No | No |
+| **Flame graph** | Yes (HTML) | Yes | Yes (SVG) | Yes (Firefox Profiler) |
+| **Call stack** | Yes (HTML) | No | No | No |
+| **Callgrind** | Yes | No | Yes | No |
+| **Graphviz dot** | Yes | Yes | No | No |
+
+## When to Use Each
+
+### ruby-prof
+
+ruby-prof is the longest-standing Ruby profiler, with its [first](./history.md) release in 2005. It has been continuously maintained for nearly two decades, evolving alongside Ruby itself from 1.8 through 4.0. Over that time it has supported every major Ruby version and platform, including Windows — a rarity among Ruby C extensions.
+
+Being a tracing profiler, ruby-prof provides *exact* information about your program. It tracks every thread, every fiber and every method call. It shines with its support for multiple measurements modes and excellent reporting capabilities. 
+
+ruby-prof can be used from the [command line](getting-started.md#command-line) with no code changes, or via an API for more control.
+
+The biggest downsides of ruby-prof are:
+
+* It adds significant overhead for running programs, so is not suitable for production use
+* It must start a Ruby program, it cannot attach to an already running program
+
+### stackprof
+
+[stackprof](https://github.com/tmm1/stackprof) is a low-overhead, sampling profiler that is good for development. It adds minimal overhead while still providing useful flame graphs and per-line hit counts. A good choice when you want something lightweight and well-established.
+
+The biggest downsides of stackprof are:
+
+ * Single-thread only
+ * Linux only for time-based modes
+
+### rbspy
+
+[rbspy](https://github.com/rbspy/rbspy) is a sampling profiler best for profiling in production or when you cannot modify the application code. As an external process, it attaches to a running Ruby process by PID with zero code changes. It is particularly useful for profiling third-party Ruby applications (Chef, Puppet, etc.), investigating slow test runs, or quick profiling of scripts via `rbspy record ruby my-script.rb`. Supports the widest range of Ruby versions.
+
+The biggest downsides of rbspy are:
+
+* No allocation profiling
+* No call graph or caller/callee data
+
+### vernier
+
+[vernier](https://github.com/jhawthorn/vernier) is a sampling profiler best for diagnosing concurrency issues and understanding GVL contention. It is the only Ruby profiler that reports GVL state, GC pauses and idle time. Its Firefox Profiler integration provides rich interactive visualizations with per-thread timelines.
+
+The biggest downsides of vernier are:
+
+* Requires Ruby 3.2.1+
+* No Windows support
+
+### rack-mini-profiler
+
+[rack-mini-profiler](https://github.com/MiniProfiler/rack-mini-profiler) is a "batteries-included" profiling tool for Rails and Rack applications. It uses stackprof under the hood for CPU profiling while also supporting memory profiling. It is a good choice if you want an integrated profiling solution that works directly in the browser during development.
+
+## Memory Profiling
+
+[memory_profiler](https://github.com/SamSaffron/memory_profiler) is another profiler, but it focuses exclusively on memory usage. It uses Ruby's `ObjectSpace` API to track every object allocation during a block of code, recording the source file, line number, object type, and size via `ObjectSpace.memsize_of`. By snapshotting the GC generation before and after, it distinguishes between allocated objects (created during the block) and retained objects (still alive after GC). This makes it useful for finding memory leaks and identifying allocation-heavy code. It's pure Ruby with no C extension, so it works across Ruby versions and platforms.
+
+ruby-prof can track allocation counts via its `RubyProf::ALLOCATIONS` mode, but memory_profiler gives deeper insight into memory specifically — object sizes, retained vs allocated, and per-gem breakdowns.

data/docs/architecture.md

@@ -0,0 +1,122 @@
+# 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 graph. 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 create cycles in the graph.
+
+- **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).
+
+## 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.

data/docs/best-practices.md

@@ -0,0 +1,27 @@
+# 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

@@ -0,0 +1,130 @@
+# 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

@@ -0,0 +1,11 @@
+# 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

@@ -0,0 +1,45 @@
+# 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

@@ -0,0 +1,64 @@
+# 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

@@ -0,0 +1,33 @@
+# 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