Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 176 lines (112 sloc) 7.096 kb
bfc0db9 Added all files
Ben Brinckerhoff authored
1 = Rack::PerftoolsProfiler
473ff47 Initial commit to rack-perftools-profiler.
Ben Brinckerhoff authored
2
bfc0db9 Added all files
Ben Brinckerhoff authored
3 Middleware for profiling Rack-compatible apps using perftools.rb (http://github.com/tmm1/perftools.rb)
4
5 == Requirements
6
7 You'll need graphviz to generate call graphs using dot (for the GIF printer):
8
9 sudo port install graphviz # OS X
10 brew install graphviz # Homebrew
11 sudo apt-get install graphviz # Debian/Ubuntu
12
13 You'll need ps2pdf to generate PDFs (On OS X, ps2pdf comes is installed as part of Ghostscript)
14
15 sudo port install ghostscript # OSX
16 brew install ghostscript # Homebrew
17 sudo apt-get install ps2pdf # Debian/Ubuntu
18
19 == Configuration
20
21 Install the gem
22
23 gem install rack-perftools_profiler
24
25 Include the middleware
26
27 require 'rack/perftools_profiler'
28
7e7c67d @bhb Updated README.rdoc
bhb authored
29 For Rails 2, add the following to config/environment.rb
bfc0db9 Added all files
Ben Brinckerhoff authored
30
762b7e7 @bhb Remove version numbers from README. Updated copyright
bhb authored
31 config.gem 'rack-perftools_profiler', :lib => 'rack/perftools_profiler'
e3de3b0 Updated documentation and dependencies
Ben Brinckerhoff authored
32 require 'rack/perftools_profiler'
097af6f @bhb Update README
bhb authored
33 config.middleware.use ::Rack::PerftoolsProfiler, :default_printer => 'gif'
bfc0db9 Added all files
Ben Brinckerhoff authored
34
8666dc3 @bhb Updated README
bhb authored
35 For Rails 3, add the following to your Gemfile
7e7c67d @bhb Updated README.rdoc
bhb authored
36
762b7e7 @bhb Remove version numbers from README. Updated copyright
bhb authored
37 gem 'rack-perftools_profiler', :require => 'rack/perftools_profiler'
7e7c67d @bhb Updated README.rdoc
bhb authored
38
8666dc3 @bhb Updated README
bhb authored
39 and add the following to config/application.rb
7e7c67d @bhb Updated README.rdoc
bhb authored
40
097af6f @bhb Update README
bhb authored
41 config.middleware.use ::Rack::PerftoolsProfiler, :default_printer => 'gif', :bundler => true
7e7c67d @bhb Updated README.rdoc
bhb authored
42
bfc0db9 Added all files
Ben Brinckerhoff authored
43 For Sinatra, call 'use' inside a configure block, like so:
44
45 configure :profiling do
097af6f @bhb Update README
bhb authored
46 use ::Rack::PerftoolsProfiler, :default_printer => 'gif'
bfc0db9 Added all files
Ben Brinckerhoff authored
47 end
48
49 For Rack::Builder, call 'use' inside the Builder constructor block
50
51 Rack::Builder.new do
097af6f @bhb Update README
bhb authored
52 use ::Rack::PerftoolsProfiler, :default_printer => 'gif'
bfc0db9 Added all files
Ben Brinckerhoff authored
53 end
54
55 == Options
56
57 * :default_printer - can be set to 'text', 'gif', or 'pdf'. Default is :text
afe7b3c @bhb Updated README to include info on 'methods' mode
bhb authored
58 * :mode - can be set to 'cputime', 'methods', 'objects', 'walltime'. Default is :cputime. See the 'Profiling Modes' section below.
bfc0db9 Added all files
Ben Brinckerhoff authored
59 * :frequency - in :cputime mode, the number of times per second the app will be sampled. Default is 100 (times/sec)
e27892c @bhb Merge remote branch 'AlekSi/master'
bhb authored
60 * :bundler - run the profiler binary using 'bundle' if set to true. Default is false
61 * :gemfile_dir - directory with Gemfile. Default is the current directory.
bfc0db9 Added all files
Ben Brinckerhoff authored
62
63 == Usage
64
04f68de @bhb Updated README to stop using the word 'mode' to mean two different th…
bhb authored
65 There are two ways to profile your app: with a single request or with multiple requests.
bfc0db9 Added all files
Ben Brinckerhoff authored
66
04f68de @bhb Updated README to stop using the word 'mode' to mean two different th…
bhb authored
67 To profile with a single request, visit the URL you want to profile, but
bfc0db9 Added all files
Ben Brinckerhoff authored
68 add the 'profile' and (optionally) the 'times' GET params (which will rerun the action
69 the specified number of times).
70
71 Example:
7e7c67d @bhb Updated README.rdoc
bhb authored
72 curl http://localhost:3000/foobar?profile=true&times=3
bfc0db9 Added all files
Ben Brinckerhoff authored
73
74 Note that this will change the status, body, and headers of the response (you'll get
75 back the profiling data, NOT the original response).
76
04f68de @bhb Updated README to stop using the word 'mode' to mean two different th…
bhb authored
77 You can also profile your application using multiple requests. When you profile using this method,
78 all responses are normal. You must visit \_\_stop\_\_ to complete profiling and then you can view
79 the profiling data by visiting \_\_data\_\_.
bfc0db9 Added all files
Ben Brinckerhoff authored
80
81 Example:
7e7c67d @bhb Updated README.rdoc
bhb authored
82 curl http://localhost:3000/__start__
83 curl http://localhost:3000/foobar
84 curl http://localhost:3000/foobaz
85 curl http://localhost:3000/__stop__
86 curl http://localhost:3000/__data__
bfc0db9 Added all files
Ben Brinckerhoff authored
87
88 == Profiling Data Options
89
04f68de @bhb Updated README to stop using the word 'mode' to mean two different th…
bhb authored
90 Regardless of how you profile your application, you can add additional params to change how the
91 data is displayed. When using a single request, these params are just added to the URL being profiled.
92 When using multiple requests, they are added to the \_\_data\_\_ URL.
bfc0db9 Added all files
Ben Brinckerhoff authored
93
94 * printer - overrides the default_printer option (see above)
95 * ignore - a regular expression of the area of code to ignore
96 * focus - a regular expression of the area of code to solely focus on.
97
98 (for 'ignore' and 'focus', please see http://google-perftools.googlecode.com/svn/trunk/doc/cpuprofile.html#pprof
99 for more details)
100
148cc7c @bhb Updated README
bhb authored
101 == Profiling Modes
102
04f68de @bhb Updated README to stop using the word 'mode' to mean two different th…
bhb authored
103 perftools.rb (and therefore, the Rack middleware) can be put into three different profiling modes.
148cc7c @bhb Updated README
bhb authored
104
105 * CPU time mode - Reports how many CPU cycles are spent in each section of code. This is the default and can be enabled by setting ':mode => :cputime'
afe7b3c @bhb Updated README to include info on 'methods' mode
bhb authored
106 * Method call mode - Report how many method calls are made inside each method. Enable by setting ':mode => :methods'
148cc7c @bhb Updated README
bhb authored
107 * Object allocation mode - Reports the percentage of object allocations performed in each section of code. Enable by setting ':mode => :objects'
afe7b3c @bhb Updated README to include info on 'methods' mode
bhb authored
108 * Wall time mode - Reports the amount of time (as in, wall clock time) spent in each section of code. Enable by setting ':mode => :walltime'
148cc7c @bhb Updated README
bhb authored
109
110 For example, consider the following Sinatra application:
111
112 require 'sinatra'
113 require 'rack/perftools_profiler'
114
115 configure do
097af6f @bhb Update README
bhb authored
116 use ::Rack::PerftoolsProfiler, :default_printer => 'gif', :mode => :cputime
148cc7c @bhb Updated README
bhb authored
117 end
118
119 get "/slow" do
120 sleep(3)
121 "hello"
122 end
123
124 In the default mode, there will be no profiling data for the 'slow' route, because it uses few CPU cycles (You'll see the message 'No nodes to print').
125
126 If you change the mode to ':walltime', you'll get profiling data, since the call to 'sleep' causes the code to spend several seconds of wall time in the block.
127
f924349 @bhb Added documentation
bhb authored
128 == Overriding the Profiling mode
129
afe7b3c @bhb Updated README to include info on 'methods' mode
bhb authored
130 You can also switch the profiling mode on a per-request basis, but ONLY if you are switching to 'methods' or 'objects' mode. Due to the implementation of perftools.rb, it is NOT possible to switch to 'walltime' or 'cputime' modes.
f924349 @bhb Added documentation
bhb authored
131
afe7b3c @bhb Updated README to include info on 'methods' mode
bhb authored
132 To switch to another mode, provide the 'mode' option. When profiling with a single request, add the option to the URL profiled:
f924349 @bhb Added documentation
bhb authored
133
134 curl http://localhost:3000/foobar?profile=true&mode=objects
135
136 When profiling using multiple requests, add the option when visiting \_\_start\_\_ :
137
138 curl http://localhost:3000/__start__?mode=objects
139
140 If the 'mode' option is omitted, the middleware will default to the mode specified at configuration.
141
148cc7c @bhb Updated README
bhb authored
142 == Changing behavior with environment variables
143
144 The mode and frequency settings are enabled by setting environment variables. Some of these environment variables must be set before 'perftools' is required. If you only require 'rack/perftools_profiler', it will do the right thing (require 'perftools' after setting the environment variables).
145
146 If you need to require 'perftools' before 'rack/perftools_profiler' (or you have other problems changing the mode or frequency), try using these environment variables yourself.
147
148 Setting the frequency:
149 CPUPROFILE_FREQUENCY=500 ruby your_app.rb
150
151 Setting the mode to 'wall time'
152 CPUPROFILE_REALTIME=1 ruby your_app.rb
153
154 Setting the mode to 'object allocation'
155 CPUPROFILE_OBJECTS=1 ruby your_app.rb
156
bfc0db9 Added all files
Ben Brinckerhoff authored
157 == Acknowledgments
158
159 A huge thanks to Aman Gupta for the awesome perftools.rb gem.
160
097af6f @bhb Update README
bhb authored
161 The basic idea and initial implementation of the middleware was heavily influenced by Rack::Profiler from rack-contrib.
473ff47 Initial commit to rack-perftools-profiler.
Ben Brinckerhoff authored
162
163 == Note on Patches/Pull Requests
164
165 * Fork the project.
166 * Make your feature addition or bug fix.
167 * Add tests for it. This is important so I don't break it in a
168 future version unintentionally.
169 * Commit, do not mess with rakefile, version, or history.
f05012a README fixes
Ben Brinckerhoff authored
170 (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
473ff47 Initial commit to rack-perftools-profiler.
Ben Brinckerhoff authored
171 * Send me a pull request. Bonus points for topic branches.
172
173 == Copyright
174
762b7e7 @bhb Remove version numbers from README. Updated copyright
bhb authored
175 Copyright (c) 2010-2011 Ben Brinckerhoff. See LICENSE for details.
Something went wrong with that request. Please try again.