1Devel::Profiler(3)    User Contributed Perl Documentation   Devel::Profiler(3)
2
3
4

NAME

6       Devel::Profiler - a Perl profiler compatible with dprofpp
7

SYNOPSIS

9       To profile a Perl script, run it with a command-line like:
10
11         $ perl -MDevel::Profiler script.pl
12
13       Or add a line using Devel::Profiler anywhere your script:
14
15         use Devel::Profiler;
16
17       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
20         $ dprofpp
21
22       See the "dprofpp" man page for details on examining the output.
23
24       For Apache/mod_perl profiling see the Devel::Profiler::Apache module
25       included with Devel::Profiler.
26

DESCRIPTION

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
32       NOTE: If Devel::DProf works for your application then there is no
33       reason to use this module.
34

RATIONALE

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
43       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
48       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
58       Thus, Devel::Profiler was born - an attempt to create a dprofpp-
59       compatible profiler that avoids Devel::DProf's most debilitating bugs.
60

USAGE

62       The simplest way to use Devel::Profiler is to add it on the command-
63       line before a script to profile:
64
65         perl -MDevel::Profiler script.pl
66
67       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
72         use Devel::Profiler buffer_size => 1024;
73
74       The available options are listed in the OPTIONS section below.
75

OPTIONS

77       The available options are:
78
79       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
86             use Devel::Profiler output_file => "profiler.out";
87
88           Then you'll need to invoke "dprofpp" like this:
89
90             dprofpp profiler.out
91
92       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
100       bad_pkgs
101           Devel::Profiler can skip profiling subroutines in a configurable
102           list of packages.  The default list is:
103
104             [qw(UNIVERSAL Time::HiRes B Carp Exporter Cwd Config CORE DynaLoader
105              XSLoader AutoLoader)]
106
107           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
112           Devel::Profiler never profiles pragmatic modules which are in all
113           lower-case.
114
115           In addition the DB package is always skipped since trying to
116           instrument the subroutines in DB will crash Perl.
117
118           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
122       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
130           For example, to never profile packages in the Apache namespace you
131           would write:
132
133             use Devel::Profiler
134               package_filter => sub {
135                                     my $pkg = shift;
136                                     return 0 if $pkg =~ /^Apache/;
137                                     return 1;
138                                 };
139
140           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
144           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
149       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
155       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
161           For example, to avoid wrapping all upper-case subroutines:
162
163             use Devel::Profiler
164               sub_filter => sub {
165                                    my ($pkg, $sub) = @_;
166                                    return 0 if $sub =~ /^[A-Z_]+$/;
167                                    return 1;
168                                 };
169
170       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
178       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

CAVEATS

186       This profiler has a number of inherent weaknesses that should be
187       acknowledged.  Here they are:
188
189       •   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
196       •   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
203       •   Devel::Profiler uses Perl's "times()" function and as a result it
204           won't work on systems that don't have "times()".
205
206       •   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
211       •   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

TODO

216       My todo list - feel free to send me patches for any of these!
217
218       •   Add code to find and instrument anonymous subs.  Maybe use B::Utils
219           and B::Generate?  Good grief.
220
221       •   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
225       •   Override require (and do(FILE) and eval""?) to automatically re-
226           scan for subs.  (Requires todo above to avoid horking the results.)
227
228       •   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
238       •   Add better support for AUTOLOAD in all its myriad uses.
239
240       •   Find a way to either ignore or handle overloaded packages.
241

BUGS

243       I know of no bugs aside from the caveats listed above.  If you find
244       one, please file a bug report at:
245
246         http://rt.cpan.org
247
248       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

ACKNOWLEDGMENTS

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
257       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
262       In addition, the following people have contributed bug reports, feature
263       suggestions and/or code patches:
264
265         Automated Perl Test Account
266         Andreas Marcel Riechert
267         Simon Rosenthal
268         Jasper Zhao
269
270       Thanks!
271
273       Copyright (C) 2002 Sam Tregar
274
275       This program is free software; you can redistribute it and/or modify it
276       under the same terms as Perl 5 itself.
277

AUTHOR

279       Sam Tregar <sam@tregar.com>
280

SEE ALSO

282       Devel::DProf, Devel::AutoProfiler
283

POD ERRORS

285       Hey! The above document had some coding errors, which are explained
286       below:
287
288       Around line 924:
289           You forgot a '=back' before '=head1'
290
291
292
293perl v5.34.0                      2022-01-21                Devel::Profiler(3)
Impressum