ruby-prof 2.0.3 → 2.0.5

data/docs/advanced-usage.md

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

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

@@ -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.