NAME

       Devel::Profile - tell me why my perl program runs so slowly

SYNOPSIS

           perl -d:Profile program.pl
           less prof.out

DESCRIPTION

       The Devel::Profile package is a Perl code profiler.  This will collect information on the
       execution time of a Perl script and of the subs in that script.  This information can be
       used to determine which subroutines are using the most time and which subroutines are
       being called most often.

       To profile a Perl script, run the perl interpreter with the -d debugging switch.  The
       profiler uses the debugging hooks.  So to profile script test.pl the following command
       should be used:

               perl -d:Profile test.pl

       When the script terminates (or periodicly while running, see ENVIRONMENT) the profiler
       will dump the profile information to a file called prof.out. This file is human-readable,
       no additional tool is required to read it.

       Note: Statistics are kept per sub, not per line.

ENVIRONMENT

       "PERL_PROFILE_SAVETIME"
           How often to save profile data while running, in seconds, 0 to save only at exit.  The
           default is every 2 minutes.

       "PERL_PROFILE_FILENAME"
           Filename to save profile data to, default is prof.out

       "PERL_PROFILE_DONT_OTHER"
           Time spent running code not in 'subs' (such as naked code in main) won\'t get
           accounted for in the normal manner. By default, we account for this time in the sub
           '<other>'. With this variable set, we leave it as 'missing' time.  This reduces the
           effective runtime of the program, and the calculated percentages.

OUTPUT FORMAT

       example output:

           time elapsed (wall):   86.8212
           time running program:  65.7657  (75.75%)
           time profiling (est.): 21.0556  (24.25%)
           number of calls:       647248

           %Time    Sec.     #calls   sec/call  F  name
           31.74   20.8770     2306   0.009053     Configable::init_from_config
           20.09   13.2116   144638   0.000091     Configable::init_field_from_config
           17.49   11.5043   297997   0.000039     Configable::has_attr
            8.22    5.4028      312   0.017317     MonEl::recycle
            7.54    4.9570    64239   0.000077     Configable::inherit
            5.02    3.3042   101289   0.000033     MonEl::unique
           [...]

       This is a small summary, followed by one line per sub.

       time elapsed (wall)
           This is the total time elapsed.

       time running program
           This is the amount of time spent running your program.

       time profiling
           This is the amount of time wasted due to profiler overhead.

       number of calls
           This is the total number of subroutine calls your program made.

       Followed by one line per subroutine.

       name
           The name of the subroutine.

       %Time
           The percentage of the total program runtime used by this subroutine.

       Sec.
           The total number of seconds used by this subroutine.

       #calls
           The number of times this subroutine was called.

       sec/call
           The average number of seconds this subroutines takes each time it is called.

       F   Flags.

           "*" pseudo-function to account for otherwise unacounted for time.

           "?" At least one call of this subroutine did not return (typically because of an
               "exit", or "die"). The statistics for it may be slightly off.

           "x" At least one call of this subroutine trapped an exception.  The statistics for it
               may be slightly off.

LONG RUNNING PROGRAMS

       This module was written so that the author could profile a large long-running (daemon)
       program. Since normally, this program never exited, saving profiling data only at program
       exit was not an interesting option. This module will save profiling data periodically
       based on $PERL_PROFILE_SAVETIME, or the program being profiled can call "DB::save()" at
       any time. This allows you to watch your profiling data while the program is running.

       The above program also had a very large startup phase (reading config files, building data
       structures, etc), the author wanted to see profiling data for the startup phase, and for
       the running phase separately. The running program can call "DB::reset()" to save the
       profiling data and reset the statistics. Once reset, only "stuff" that happens from that
       point on will be reflected in the profile data file.

       By default, reset is attached to the signal handler for "SIGUSR2".  Using a perl built
       with "safe signal handling" (5.8.0 and higher), you may safely send this signal to control
       profiling.

BUT I WANT INCLUSIVE TIMES NOT EXCLUSIVE TIMES

       Please see the spin-off module Devel::DProfLB.

BUGS

       Some buggy XS based perl modules can behave erroneously when run under the perl debugger.
       Since Devel::Profile uses the perl debugger interfaces, these modules will also behave
       erroneously when being profiled.

       There are no known bugs in this module.

LICENSE

       This software may be copied and distributed under the terms found in the Perl "Artistic
       License".

       A copy of the "Artistic License" may be found in the standard Perl distribution.

SEE ALSO

           Yellowstone National Park.
           Devel::DProfLB

AUTHOR

       Jeff Weisberg - http://www.tcp4me.com/