Devel::Profiler man page on Fedora

Man page or keyword search:  
man Server   31170 pages
apropos Keyword Search (all sections)
Output format
Fedora logo
[printable version]

Devel::Profiler(3)    User Contributed Perl Documentation   Devel::Profiler(3)

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:

       ·   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)
[top]

List of man pages available for Fedora

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net