Devel::Profiler(3) User Contributed Perl Documentation Devel::Profiler(3)NAMEDevel::Profiler - a Perl profiler compatible with dprofpp
SYNOPSIS
To profile a Perl script, run it with a command-line like:
$ perl -MDevel::Profiler script.pl
Or add a line using Devel::Profiler anywhere your script:
use Devel::Profiler;
Use the script as usual and perform the operations you want to profile.
Then run "dprofpp" to analyze the generated file (called "tmon.out"):
$ dprofpp
See the "dprofpp" man page for details on examining the output.
For Apache/mod_perl profiling see the Devel::Profiler::Apache module
included with Devel::Profiler.
DESCRIPTION
This module implements a Perl profiler that outputs profiling data in a
format compatible with "dprofpp", Devel::DProf's profile analysis tool.
It is meant to be a drop-in replacement for Devel::DProf.
NOTE: If Devel::DProf works for your application then there is no
reason to use this module.
RATIONALE
I created this module because I desperately needed a profiler to
optimize a large Apache/mod_perl application. Devel::DProf, however,
insisted on seg-faulting on every request. I spent many days trying to
fix Devel::DProf, but eventually I had to admit that I wasn't going to
be able to do it. Devel::DProf's virtuoso creator, Ilya Zakharevich,
was unable to spend the time to fix it. Game over.
My next stop brought me to Devel::AutoProfiler by Greg London. This
module is a pure-Perl profiler. Reading the code convinced me that it
was possible to write profiler without going the route that led to
Devel::DProf's extremely difficult code.
Devel::AutoProfiler is a good module but I found several problems.
First, Devel::AutoProfiler doesn't output data in the format used by
"dprofpp". I like "dprofpp" - it has every option I want and the
"tmon.out" format it supports is well designed. In contrast,
Devel::AutoProfiler stores its profiling data in memory and then dumps
its data to STDOUT all in one go. As a result, Devel::AutoProfiler is,
potentially, a heavy user of memory. Finally, Devel::AutoProfiler has
some (seemingly) arbitrary limitations; for example, it won't profile
subroutines that begins with "__".
Thus, Devel::Profiler was born - an attempt to create a dprofpp-
compatible profiler that avoids Devel::DProf's most debilitating bugs.
USAGE
The simplest way to use Devel::Profiler is to add it on the command-
line before a script to profile:
perl -MDevel::Profiler script.pl
However, if you want to modify the way Devel::Profiler works you'll
need to add a line to your script. This allows you to specify options
that control Devel::Profiler's behavior. For example, this sets the
internal buffer size to 1024 bytes.
use Devel::Profiler buffer_size => 1024;
The available options are listed in the OPTIONS section below.
OPTIONS
The available options are:
output_file
This option controls the name of the output file. By default this
is "tmon.out" and will be placed in the current directory. If you
change this option then you'll have to specify it on the command-
line to "dprofpp". For example, if you use this line to invoke
Devel::Profiler:
use Devel::Profiler output_file => "profiler.out";
Then you'll need to invoke "dprofpp" like this:
dprofpp profiler.out
buffer_size
Devel::Profiler uses an internal buffer to avoid writing to the
disk before and after every subroutine call, which would greatly
slow down your program. The default buffer_size is 64k which
should be large enough for most uses. If you set this value to 0
then Devel::Profiler will write data to disk as soon as it is
available.
bad_pkgs
Devel::Profiler can skip profiling subroutines in a configurable
list of packages. The default list is:
[qw(UNIVERSAL Time::HiRes B Carp Exporter Cwd Config CORE DynaLoader
XSLoader AutoLoader)]
You can specify your own array-ref of packages to avoid using this
option. Note that by using this option you're overwriting the list
not adding to it. As a result you'll generally want to include at
many of the packages listed above in your list.
Devel::Profiler never profiles pragmatic modules which are in all
lower-case.
In addition the DB package is always skipped since trying to
instrument the subroutines in DB will crash Perl.
Finally, Devel::Profiler never profiles pragmatic modules which it
detects by their being entirely lower-case. Example of pragmatic
modules you've probably heard of are "strict", "warnings", etc.
package_filter
This option allows you to handle package selection more flexibly by
allowing you to construct a callback that will be used to control
which packages are profiled. When the callback returns true the
package will be profiled, false and it will not. A false return
will also inhibit profiling of child packages, so be sure to allow
'main'!
For example, to never profile packages in the Apache namespace you
would write:
use Devel::Profiler
package_filter => sub {
my $pkg = shift;
return 0 if $pkg =~ /^Apache/;
return 1;
};
The callback is consider after consulting bad_pkgs, so you will
still need to modify bad_pkgs if you intend to profile a default
member of that list.
If you pass an array-ref to package_filter you can specify a list
of filters. These will be consulted in-order with the first to
return 0 causing the package to be discarded, like a short-
circuiting "and" operator.
bad_subs
You can specify an array-ref containing a list of subs not to
profile. There are no items in this list by default. Be sure to
specify the fully-qualified name - i.e. "Time::HiRes::time" not
just "time".
sub_filter
The sub_filter option allows you to specify one or more callbacks
to be used to decide whether to profile a subroutine or not. The
callbacks will recieve two parameters - the package name and the
subroutine name.
For example, to avoid wrapping all upper-case subroutines:
use Devel::Profiler
sub_filter => sub {
my ($pkg, $sub) = @_;
return 0 if $sub =~ /^[A-Z_]+$/;
return 1;
};
override_caller
By default Devel::Profiler will override Perl's builtin caller().
The overriden caller() will ignore the frames generated by
Devel::Profiler and keep code that depends on caller() working
under the profiler. Set this option to 0 to inhibit this behavior.
Be aware that this is likely to break many modules, particularly
ones that implement their own exporting.
hz This variable sets the number of ticks-per-second in the timing
routines. By default it is set to 1000, which should be good
enough to capture the accuracy of most times() implementations
without spamming the output file with timestamps. Setting this too
low will reduce the accuracy of your data. In general you should
not need to change this setting.
CAVEATS
This profiler has a number of inherent weaknesses that should be
acknowledged. Here they are:
· Devel::Profiler doesn't profile anonymous subroutines. It works by
walking package symbol tables so it won't notice routines with no
names. As a result the time spent in anonymous subroutines is
credited to their named callers. This may change in the future,
but if it does I'll add an option to restrict the profiler to named
subs.
· Devel::Profiler won't notice if you compile new subs after
execution begins (after INIT, to be accurate). This happens when
modules use the Autoloader or Selfloader or include their own
mechanisms for creating subroutines on the fly (usually from
AUTOLOAD). This also includes modules that are loaded on-demand
with require.
· Devel::Profiler uses Perl's "times()" function and as a result it
won't work on systems that don't have "times()".
· Devel::Profiler won't capture time used before execution begins -
for example, in BEGIN blocks. I think of this as an advantage
since I rarely need to optimize initialization performance, but for
frequently run programs this might unfortunate.
· Overloading causes Devel::Profiler serious indigestion. You'll
have to exclude overloading packages with bad_pkgs or
package_filter until this changes.
TODO
My todo list - feel free to send me patches for any of these!
· Add code to find and instrument anonymous subs. Maybe use B::Utils
and B::Generate? Good grief.
· Allow users to request a re-scan for subs. This is almost possible
by calling scan() except that scan() is missing code to inhibit
profiling while scanning.
· Override require (and do(FILE) and eval""?) to automatically re-
scan for subs. (Requires todo above to avoid horking the results.)
· Do research into the differences between Devel::DProf's output and
Devel::Profiler's. Usually they are quite close but occasionally
they disagree by orders of magnitude. For example, running
HTML::Template's test suite under Devel::DProf shows output()
taking NO time but Devel::Profiler shows around 10% of the time is
in output(). I don't know which to trust but my gut tells me
something is wrong with Devel::DProf. HTML::Template::output() is
a big routine that's called for every test. Either way, something
needs fixing.
· Add better support for AUTOLOAD in all its myriad uses.
· Find a way to either ignore or handle overloaded packages.
BUGS
I know of no bugs aside from the caveats listed above. If you find
one, please file a bug report at:
http://rt.cpan.org
Alternately you can email me directly at sam@tregar.com. Please
include the version of the module and a complete test case that
demonstrates the bug.
ACKNOWLEDGMENTS
I learned a great deal from the original Perl profiler, Devel::DProf by
Ilya Zakharevich. It provided the design for the output format as well
as introducing me to many useful techniques.
Devel::AutoProfiler by Greg London proved to me that a pure-Perl
profiler was possible and that it need not rely on the buggy DB
facilities. Without seeing this module I probably would have given up
on the project entirely.
In addition, the following people have contributed bug reports, feature
suggestions and/or code patches:
Automated Perl Test Account
Andreas Marcel Riechert
Simon Rosenthal
Jasper Zhao
Thanks!
COPYRIGHT AND LICENSE
Copyright (C) 2002 Sam Tregar
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl 5 itself.
AUTHOR
Sam Tregar <sam@tregar.com>
SEE ALSO
Devel::DProf, Devel::AutoProfiler
POD ERRORS
Hey! The above document had some coding errors, which are explained
below:
Around line 923:
You forgot a '=back' before '=head1'
perl v5.14.0 2011-06-16 Devel::Profiler(3)