Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Devel::SmallProf(3)   User Contributed Perl Documentation  Devel::SmallProf(3)

       Devel::SmallProf	- per-line Perl	profiler

	       perl5 -d:SmallProf

       The Devel::SmallProf profiler is	focused	on the time taken for a
       program run on a	line-by-line basis.  It	is intended to be as "small"
       in terms	of impact on the speed and memory usage	of the profiled
       program as possible and also in terms of	being simple to	use.  Those
       statistics are placed in	the file smallprof.out in the following

	       <num> <time> <ctime> <line>:<text>

       where <num> is the number of times that the line	was executed, <time>
       is the amount of	"wall time" (time according the	the clock on the wall
       vs. cpu time) spent executing it, <ctime> is the	amount of cpu time
       expended	on it and <line> and <text> are	the line number	and the	actual
       text of the executed line (read from the	file).

       The package uses	the debugging hooks in Perl and	thus needs the -d
       switch, so to profile, use the command:

	       perl5 -d:SmallProf

       Once the	script is done,	the statistics in smallprof.out	can be sorted
       to show which lines took	the most time.	The output can be sorted to
       find which lines	take the longest, either with the sort command:

	       sort -k 2nr,2 smallprof.out | less

       or a perl script:

	       @sorted = sort {(split(/\s+/,$b))[2] <=>
			       (split(/\s+/,$a))[2]} <PROF>;
	       close PROF;
	       print join('',@sorted);

       o   The "wall time" readings come from Time::HiRes and are reasonably
	   useful, at least on my system.  The cpu times come from the 'times'
	   built-in and	the granularity	is not necessarily as small as with
	   the wall time.  On some systems this	column may be useful.  On
	   others it may not.

       o   SmallProf does attempt to make up for its shortcomings by
	   subtracting a small amount from each	timing (null time
	   compensation).  This	should help somewhat with the accuracy.

       o   SmallProf depends on	the Time::HiRes	package	to do its timings.  It
	   claims to require version 1.20, but may work	with earlier versions,
	   depending on	your platform.

       SmallProf has 4 variables which can be used during your script to
       affect what gets	profiled.

       $DB::drop_zeros (z)
	   If you do not wish to see lines which were never called, set	the
	   variable "$DB::drop_zeros = 1".  With "drop_zeros" set, SmallProf
	   can be used for basic coverage analysis.

       $DB::profile (p)
	   To turn off profiling for a time, insert a "$DB::profile = 0" into
	   your	code (profiling	may be turned back on with "$DB::profile =
	   1").	 All of	the time between profiling being turned	off and	back
	   on again will be lumped together and	reported on the	"$DB::profile
	   = 0"	line.  This can	be used	to summarize a subroutine call or a
	   chunk of code.

	   To only profile code	in a certain package, set the %DB::packages
	   array.  For example,	to see only the	code in	packages "main"	and
	   "Test1", do this:

		   %DB::packages = ( 'main' => 1, 'Test1' => 1 );

       $DB::grep_format	(g)
	   Generates output on a format	similar	to grep	easily parseable from
	   tools like Emacs (see below).

	   grep	format output appears as:

	     file name : line num : count : time : ctime : source


	     file name : line num : count : time : ctime : (eval n: line num) source

	   for code inside evals.

	   Times appear	in miliseconds.

       These variables can be put in a file called .smallprof in the current
       directory.  For example,	a .smallprof containing

	       $DB::drop_zeros = 1;
	       $DB::profile = 0;

       will set	SmallProf to not report	lines which are	never touched for any
       file profiled in	that directory and will	set profiling off initially
       (presumably to be turned	on only	for a small portion of code).

       Environment variable "SMALLPROF_CONFIG" can be also used	to set those
       flags, i.e:

	  SMALLPROF_CONFIG=zg perl -d:SmallProf	my_script.plx

       activates "drop_zeros" and "grep_format"	modes.

       Just the	usual

	       perl Makefile.PL
	       make test
	       make install

       and should install fine via the CPAN module.

       Subroutine calls	are currently not under	the control of %DB::packages.
       This should not be a great inconvenience	in general.

       The handling of evals is	bad news.  This	is due to Perl's handling of
       evals under the -d flag.	 For certain evals, caller() returns '(eval
       n)' for the filename and	for others it doesn't.	For some of those
       which it	does, the array	"@{'_<filename'}" contains the code of the
       eval.  For others it doesn't.  Sometime,	when I've an extra tuit	or
       two, I'll figure	out why	and how	I can compensate for this.  (Note:
       5.6.0 made some debugging changes.  This	may now	be fixed, I'm not

       SmallProf must be invoked from the command line.	 If it is included on
       the shebang line, the file in which it is included will not be visible
       in the symbol table.  Profiling will continue as	expected, but the
       contents	of the source lines will not be	listed.	 This is new as	of

       Comments, advice	and questions are welcome.  If you see inefficent
       stuff in	this module and	have a better way, please let me know.

       1.  Use the "DB::grep_format" flag to turn on grep like format, i.e.

	     SMALLPROF_CONFIG=g	perl -d:SmallProf

       2.  Tell	Emacs/XEmacs to	read smallprof.out as grep output:

	     M-x grep RET C-a C-k cat smallprof.out RET

       3.  Point and click to go to the	script hot spots!

       Devel::SmallProf	was developed by Ted Ashton <>. It is
       currently being maintained by Salvador FandiA+-o	<>.

       SmallProf was developed from code originally posted to usenet by
       Philippe	Verdret	<>.	Special	thanks
       to Geoffrey Broadwell <> for	his assistance on the
       Win32 platform and to Philippe for his patient assistance in testing
       and debugging.

       Copyright (c) 1997-2000 Ted Ashton

       Copyright (c) 2003-2007 Salvador	FandiA+-o

       This module is free software and	can be redistributed and/or modified
       under the same terms as Perl itself.

       Devel::FastProf is a simplified and much	faster version of this module.

       Devel::DProf, Time::HiRes.

       Hey! The	above document had some	coding errors, which are explained

       Around line 386:
	   Non-ASCII character seen before =encoding in	'FandiA+-o'. Assuming

perl v5.32.0			  2007-05-11		   Devel::SmallProf(3)


Want to link to this manual page? Use this URL:

home | help