1Devel::Profiler(3) User Contributed Perl Documentation Devel::Profiler(3)
2
6 Devel::Profiler - a Perl profiler compatible with dprofpp
7
9 To profile a Perl script, run it with a command-line like:
10 $ perl -MDevel::Profiler script.pl
12 Or add a line using Devel::Profiler anywhere your script:
14 use Devel::Profiler;
16 Use the script as usual and perform the operations you want to profile.
18 Then run "dprofpp" to analyze the generated file (called "tmon.out"):
19 $ dprofpp
21 See the "dprofpp" man page for details on examining the output.
23 For Apache/mod_perl profiling see the Devel::Profiler::Apache module
25 included with Devel::Profiler.
26
28 This module implements a Perl profiler that outputs profiling data in a
29 format compatible with "dprofpp", Devel::DProf's profile analysis tool.
30 It is meant to be a drop-in replacement for Devel::DProf.
31 NOTE: If Devel::DProf works for your application then there is no
33 reason to use this module.
34
36 I created this module because I desperately needed a profiler to
37 optimize a large Apache/mod_perl application. Devel::DProf, however,
38 insisted on seg-faulting on every request. I spent many days trying to
39 fix Devel::DProf, but eventually I had to admit that I wasn't going to
40 be able to do it. Devel::DProf's virtuoso creator, Ilya Zakharevich,
41 was unable to spend the time to fix it. Game over.
42 My next stop brought me to Devel::AutoProfiler by Greg London. This
44 module is a pure-Perl profiler. Reading the code convinced me that it
45 was possible to write profiler without going the route that led to
46 Devel::DProf's extremely difficult code.
47 Devel::AutoProfiler is a good module but I found several problems.
49 First, Devel::AutoProfiler doesn't output data in the format used by
50 "dprofpp". I like "dprofpp" - it has every option I want and the
51 "tmon.out" format it supports is well designed. In contrast,
52 Devel::AutoProfiler stores its profiling data in memory and then dumps
53 its data to STDOUT all in one go. As a result, Devel::AutoProfiler is,
54 potentially, a heavy user of memory. Finally, Devel::AutoProfiler has
55 some (seemingly) arbitrary limitations; for example, it won't profile
56 subroutines that begins with "__".
57 Thus, Devel::Profiler was born - an attempt to create a dprofpp-
59 compatible profiler that avoids Devel::DProf's most debilitating bugs.
60
62 The simplest way to use Devel::Profiler is to add it on the command-
63 line before a script to profile:
64 perl -MDevel::Profiler script.pl
66 However, if you want to modify the way Devel::Profiler works you'll
68 need to add a line to your script. This allows you to specify options
69 that control Devel::Profiler's behavior. For example, this sets the
70 internal buffer size to 1024 bytes.
71 use Devel::Profiler buffer_size => 1024;
73 The available options are listed in the OPTIONS section below.
75
77 The available options are:
78 output_file
80 This option controls the name of the output file. By default this
81 is "tmon.out" and will be placed in the current directory. If you
82 change this option then you'll have to specify it on the command-
83 line to "dprofpp". For example, if you use this line to invoke
84 Devel::Profiler:
85 use Devel::Profiler output_file => "profiler.out";
87 Then you'll need to invoke "dprofpp" like this:
89 dprofpp profiler.out
91 buffer_size
93 Devel::Profiler uses an internal buffer to avoid writing to the
94 disk before and after every subroutine call, which would greatly
95 slow down your program. The default buffer_size is 64k which
96 should be large enough for most uses. If you set this value to 0
97 then Devel::Profiler will write data to disk as soon as it is
98 available.
99 bad_pkgs
101 Devel::Profiler can skip profiling subroutines in a configurable
102 list of packages. The default list is:
103 [qw(UNIVERSAL Time::HiRes B Carp Exporter Cwd Config CORE DynaLoader
105 XSLoader AutoLoader)]
106 You can specify your own array-ref of packages to avoid using this
108 option. Note that by using this option you're overwriting the list
109 not adding to it. As a result you'll generally want to include at
110 many of the packages listed above in your list.
111 Devel::Profiler never profiles pragmatic modules which are in all
113 lower-case.
114 In addition the DB package is always skipped since trying to
116 instrument the subroutines in DB will crash Perl.
117 Finally, Devel::Profiler never profiles pragmatic modules which it
119 detects by their being entirely lower-case. Example of pragmatic
120 modules you've probably heard of are "strict", "warnings", etc.
121 package_filter
123 This option allows you to handle package selection more flexibly by
124 allowing you to construct a callback that will be used to control
125 which packages are profiled. When the callback returns true the
126 package will be profiled, false and it will not. A false return
127 will also inhibit profiling of child packages, so be sure to allow
128 'main'!
129 For example, to never profile packages in the Apache namespace you
131 would write:
132 use Devel::Profiler
134 package_filter => sub {
135 my $pkg = shift;
136 return 0 if $pkg =~ /^Apache/;
137 return 1;
138 };
139 The callback is consider after consulting bad_pkgs, so you will
141 still need to modify bad_pkgs if you intend to profile a default
142 member of that list.
143 If you pass an array-ref to package_filter you can specify a list
145 of filters. These will be consulted in-order with the first to
146 return 0 causing the package to be discarded, like a short-
147 circuiting "and" operator.
148 bad_subs
150 You can specify an array-ref containing a list of subs not to
151 profile. There are no items in this list by default. Be sure to
152 specify the fully-qualified name - i.e. "Time::HiRes::time" not
153 just "time".
154 sub_filter
156 The sub_filter option allows you to specify one or more callbacks
157 to be used to decide whether to profile a subroutine or not. The
158 callbacks will recieve two parameters - the package name and the
159 subroutine name.
160 For example, to avoid wrapping all upper-case subroutines:
162 use Devel::Profiler
164 sub_filter => sub {
165 my ($pkg, $sub) = @_;
166 return 0 if $sub =~ /^[A-Z_]+$/;
167 return 1;
168 };
169 override_caller
171 By default Devel::Profiler will override Perl's builtin caller().
172 The overriden caller() will ignore the frames generated by
173 Devel::Profiler and keep code that depends on caller() working
174 under the profiler. Set this option to 0 to inhibit this behavior.
175 Be aware that this is likely to break many modules, particularly
176 ones that implement their own exporting.
177 hz This variable sets the number of ticks-per-second in the timing
179 routines. By default it is set to 1000, which should be good
180 enough to capture the accuracy of most times() implementations
181 without spamming the output file with timestamps. Setting this too
182 low will reduce the accuracy of your data. In general you should
183 not need to change this setting.
184
186 This profiler has a number of inherent weaknesses that should be
187 acknowledged. Here they are:
188 • Devel::Profiler doesn't profile anonymous subroutines. It works by
190 walking package symbol tables so it won't notice routines with no
191 names. As a result the time spent in anonymous subroutines is
192 credited to their named callers. This may change in the future,
193 but if it does I'll add an option to restrict the profiler to named
194 subs.
195 • Devel::Profiler won't notice if you compile new subs after
197 execution begins (after INIT, to be accurate). This happens when
198 modules use the Autoloader or Selfloader or include their own
199 mechanisms for creating subroutines on the fly (usually from
200 AUTOLOAD). This also includes modules that are loaded on-demand
201 with require.
202 • Devel::Profiler uses Perl's times() function and as a result it
204 won't work on systems that don't have times().
205 • Devel::Profiler won't capture time used before execution begins -
207 for example, in BEGIN blocks. I think of this as an advantage
208 since I rarely need to optimize initialization performance, but for
209 frequently run programs this might unfortunate.
210 • Overloading causes Devel::Profiler serious indigestion. You'll
212 have to exclude overloading packages with bad_pkgs or
213 package_filter until this changes.
214
216 My todo list - feel free to send me patches for any of these!
217 • Add code to find and instrument anonymous subs. Maybe use B::Utils
219 and B::Generate? Good grief.
220 • Allow users to request a re-scan for subs. This is almost possible
222 by calling scan() except that scan() is missing code to inhibit
223 profiling while scanning.
224 • Override require (and do(FILE) and eval""?) to automatically re-
226 scan for subs. (Requires todo above to avoid horking the results.)
227 • Do research into the differences between Devel::DProf's output and
229 Devel::Profiler's. Usually they are quite close but occasionally
230 they disagree by orders of magnitude. For example, running
231 HTML::Template's test suite under Devel::DProf shows output()
232 taking NO time but Devel::Profiler shows around 10% of the time is
233 in output(). I don't know which to trust but my gut tells me
234 something is wrong with Devel::DProf. HTML::Template::output() is
235 a big routine that's called for every test. Either way, something
236 needs fixing.
237 • Add better support for AUTOLOAD in all its myriad uses.
239 • Find a way to either ignore or handle overloaded packages.
241
243 I know of no bugs aside from the caveats listed above. If you find
244 one, please file a bug report at:
245 http://rt.cpan.org
247 Alternately you can email me directly at sam@tregar.com. Please
249 include the version of the module and a complete test case that
250 demonstrates the bug.
251
253 I learned a great deal from the original Perl profiler, Devel::DProf by
254 Ilya Zakharevich. It provided the design for the output format as well
255 as introducing me to many useful techniques.
256 Devel::AutoProfiler by Greg London proved to me that a pure-Perl
258 profiler was possible and that it need not rely on the buggy DB
259 facilities. Without seeing this module I probably would have given up
260 on the project entirely.
261 In addition, the following people have contributed bug reports, feature
263 suggestions and/or code patches:
264 Automated Perl Test Account
266 Andreas Marcel Riechert
267 Simon Rosenthal
268 Jasper Zhao
269 Thanks!
271
273 Copyright (C) 2002 Sam Tregar
274 This program is free software; you can redistribute it and/or modify it
276 under the same terms as Perl 5 itself.
277
279 Sam Tregar <sam@tregar.com>
280
282 Devel::DProf, Devel::AutoProfiler
283
285 Hey! The above document had some coding errors, which are explained
286 below:
287 Around line 924:
289 You forgot a '=back' before '=head1'
290perl v5.36.0 2023-01-20 Devel::Profiler(3)