ruby-prof 2.0.0 → 2.0.1

data/docs/getting-started.md

@@ -1,130 +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).
+# 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/index.md

@@ -1,45 +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).
+# 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 +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.
+# 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/generate_reports.rb

@@ -1,92 +1,92 @@
-#!/usr/bin/env ruby
-# encoding: UTF-8
-
-# Generates example reports for all ruby-prof printers.
-# Usage: ruby docs/public/examples/generate_reports.rb
-
-# To make testing/debugging easier test within this source tree versus an installed gem
-require 'bundler/setup'
-
-# Add ext directory to load path to make it easier to test locally built extensions
-ext_path = File.expand_path(File.join(__dir__, '..', '..', '..', 'ext', 'ruby_prof'))
-$LOAD_PATH.unshift(ext_path)
-
-require 'fileutils'
-require 'stringio'
-require 'uri'
-require 'ruby-prof'
-require_relative 'example'
-
-output_dir = File.join(File.dirname(__FILE__), "reports")
-FileUtils.mkdir_p(output_dir)
-
-def sanitize_local_file_links(path)
-  content = File.read(path)
-  content.gsub!(%r{href="file://[^"]*/docs/public/examples/([^"#]+)#\d+"}, 'href="../\1"')
-  content.gsub!(%r{title=".*?/docs/public/examples/([^":]+):\d+"}, 'title="\1"')
-  content.gsub!(%r{href="file://[^"]+"}, 'href="#"')
-  content.gsub!(%r{title="[^"]*(?:<internal:|&lt;internal:)[^"]+"}, 'title="internal"')
-  File.write(path, content)
-end
-
-result = RubyProf::Profile.profile(measure_mode: RubyProf::WALL_TIME) do
-  run_example
-end
-
-# Flame Graph
-File.open(File.join(output_dir, "flame_graph.html"), "wb") do |f|
-  RubyProf::FlameGraphPrinter.new(result).print(f)
-end
-
-# Call Stack
-File.open(File.join(output_dir, "call_stack.html"), "wb") do |f|
-  RubyProf::CallStackPrinter.new(result).print(f)
-end
-sanitize_local_file_links(File.join(output_dir, "call_stack.html"))
-
-# Graph HTML
-File.open(File.join(output_dir, "graph.html"), "wb") do |f|
-  RubyProf::GraphHtmlPrinter.new(result).print(f)
-end
-sanitize_local_file_links(File.join(output_dir, "graph.html"))
-
-# Graph (text)
-File.open(File.join(output_dir, "graph.txt"), "wb") do |f|
-  RubyProf::GraphPrinter.new(result).print(f)
-end
-
-# Flat
-File.open(File.join(output_dir, "flat.txt"), "wb") do |f|
-  RubyProf::FlatPrinter.new(result).print(f)
-end
-
-# Call Info
-File.open(File.join(output_dir, "call_info.txt"), "wb") do |f|
-  RubyProf::CallInfoPrinter.new(result).print(f)
-end
-
-# Dot
-dot_io = StringIO.new
-RubyProf::DotPrinter.new(result).print(dot_io)
-dot_content = dot_io.string
-File.open(File.join(output_dir, "graph.dot"), "wb") do |f|
-  f << dot_content
-end
-
-# Graphviz Online viewer with dot content embedded in URL
-viewer_url = "https://dreampuf.github.io/GraphvizOnline/?engine=dot#" + URI.encode_uri_component(dot_content)
-File.open(File.join(output_dir, "graphviz_viewer.html"), "wb") do |f|
-  f << %(<html><head><meta http-equiv="refresh" content="0;url=#{viewer_url}"></head></html>)
-end
-
-# Call Tree (calltree format)
-RubyProf::CallTreePrinter.new(result).print(path: output_dir, profile: "profile")
-# Rename PID-based filename to a stable name
-Dir.glob(File.join(output_dir, "callgrind.out.*")).each do |f|
-  FileUtils.mv(f, File.join(output_dir, "callgrind.out"))
-end
-
-puts "Reports written to #{output_dir}/"
-Dir.glob(File.join(output_dir, "*")).sort.each do |f|
-  puts "  #{File.basename(f)}"
-end
+#!/usr/bin/env ruby
+# encoding: UTF-8
+
+# Generates example reports for all ruby-prof printers.
+# Usage: ruby docs/public/examples/generate_reports.rb
+
+# To make testing/debugging easier test within this source tree versus an installed gem
+require 'bundler/setup'
+
+# Add ext directory to load path to make it easier to test locally built extensions
+ext_path = File.expand_path(File.join(__dir__, '..', '..', '..', 'ext', 'ruby_prof'))
+$LOAD_PATH.unshift(ext_path)
+
+require 'fileutils'
+require 'stringio'
+require 'uri'
+require 'ruby-prof'
+require_relative 'example'
+
+output_dir = File.join(File.dirname(__FILE__), "reports")
+FileUtils.mkdir_p(output_dir)
+
+def sanitize_local_file_links(path)
+  content = File.read(path)
+  content.gsub!(%r{href="file://[^"]*/docs/public/examples/([^"#]+)#\d+"}, 'href="../\1"')
+  content.gsub!(%r{title=".*?/docs/public/examples/([^":]+):\d+"}, 'title="\1"')
+  content.gsub!(%r{href="file://[^"]+"}, 'href="#"')
+  content.gsub!(%r{title="[^"]*(?:<internal:|&lt;internal:)[^"]+"}, 'title="internal"')
+  File.write(path, content)
+end
+
+result = RubyProf::Profile.profile(measure_mode: RubyProf::WALL_TIME) do
+  run_example
+end
+
+# Flame Graph
+File.open(File.join(output_dir, "flame_graph.html"), "wb") do |f|
+  RubyProf::FlameGraphPrinter.new(result).print(f)
+end
+
+# Call Stack
+File.open(File.join(output_dir, "call_stack.html"), "wb") do |f|
+  RubyProf::CallStackPrinter.new(result).print(f)
+end
+sanitize_local_file_links(File.join(output_dir, "call_stack.html"))
+
+# Graph HTML
+File.open(File.join(output_dir, "graph.html"), "wb") do |f|
+  RubyProf::GraphHtmlPrinter.new(result).print(f)
+end
+sanitize_local_file_links(File.join(output_dir, "graph.html"))
+
+# Graph (text)
+File.open(File.join(output_dir, "graph.txt"), "wb") do |f|
+  RubyProf::GraphPrinter.new(result).print(f)
+end
+
+# Flat
+File.open(File.join(output_dir, "flat.txt"), "wb") do |f|
+  RubyProf::FlatPrinter.new(result).print(f)
+end
+
+# Call Info
+File.open(File.join(output_dir, "call_info.txt"), "wb") do |f|
+  RubyProf::CallInfoPrinter.new(result).print(f)
+end
+
+# Dot
+dot_io = StringIO.new
+RubyProf::DotPrinter.new(result).print(dot_io)
+dot_content = dot_io.string
+File.open(File.join(output_dir, "graph.dot"), "wb") do |f|
+  f << dot_content
+end
+
+# Graphviz Online viewer with dot content embedded in URL
+viewer_url = "https://dreampuf.github.io/GraphvizOnline/?engine=dot#" + URI.encode_uri_component(dot_content)
+File.open(File.join(output_dir, "graphviz_viewer.html"), "wb") do |f|
+  f << %(<html><head><meta http-equiv="refresh" content="0;url=#{viewer_url}"></head></html>)
+end
+
+# Call Tree (calltree format)
+RubyProf::CallTreePrinter.new(result).print(path: output_dir, profile: "profile")
+# Rename PID-based filename to a stable name
+Dir.glob(File.join(output_dir, "callgrind.out.*")).each do |f|
+  FileUtils.mv(f, File.join(output_dir, "callgrind.out"))
+end
+
+puts "Reports written to #{output_dir}/"
+Dir.glob(File.join(output_dir, "*")).sort.each do |f|
+  puts "  #{File.basename(f)}"
+end