view release on metacpan or  search on metacpan

lib/Devel/Profiler.pm  view on Meta::CPAN

=item 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.

=item 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.

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

=item 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;
                      };

=item 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.

=item 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.

=head1 CAVEATS

This profiler has a number of inherent weaknesses that should be
acknowledged.  Here they are:

=over 4

=item *

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.

=item *

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.

=item *

Devel::Profiler uses Perl's C<times()> function and as a result it
won't work on systems that don't have C<times()>.

=item *