Sam Tregar > Devel-Profiler-0.04 > Devel::Profiler

Download:
Devel-Profiler-0.04.tar.gz

Dependencies

Annotate this POD (1)

CPAN RT

New  3
Open  3
View/Report Bugs
Module Version: 0.04   Source  

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'!

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:

TODO ^

My todo list - feel free to send me patches for any of these!

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

syntax highlighting: