NAME

Devel::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::'! Packages will be passed to the callback with a trailing ::.

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.

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".

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.

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.

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.

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

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

cpanm Devel::Profiler

perl -MCPAN -e shell
install Devel::Profiler