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

FreeBSD Manual Pages

  
 
  

home | help
Apache::DProf(3)      User Contributed Perl Documentation     Apache::DProf(3)

NAME
       Apache::DProf - Hook Devel::DProf into mod_perl

SYNOPSIS
	#in httpd.conf
	PerlModule Apache::DProf

DESCRIPTION
       The Apache::DProf module	will run a Devel::DProf	profiler inside	each
       child server and	write the tmon.out file	in the directory
       $ServerRoot/logs/dprof/$$ when the child	is shutdown.  Next time	the
       parent server pulls in Apache::DProf (via soft or hard restart),	the
       $ServerRoot/logs/dprof is cleaned out before new	profiles are written
       for the new children.

WHY
       It is possible to profile code run under	mod_perl with only the
       Devel::DProf module available on	CPAN.  You must	have apache version
       1.3b3 or	higher.	 When the server is started, Devel::DProf installs an
       "END" block to write the	tmon.out file, which will be run when the
       server is shutdown.  Here's how to start	and stop a server with the
       profiler	enabled:

	% setenv PERL5OPT -d:DProf
	% httpd	-X -d `pwd` &
	... make some requests to the server here ...
	% kill `cat logs/httpd.pid`
	% unsetenv PERL5OPT
	% dprofpp

       There are downsides to this approach:

       - Setting and unsetting PERL5OPT	is a pain.

       - Server	startup	code will be profiled as well, which we	are not
	 really	concerned with,	we're interested in runtime code, right?

       - It will not work unless the server is run in non-forking "-X" mode

       These limitations are due to the	assumption by Devel::DProf that	the
       code you	are profiling is running under a standard Perl binary (the one
       you run from the	command	line).	"Devel::Dprof" relies on the Perl "-d"
       switch for initialization of the	Perl debugger, which happens inside
       "perl_parse()" function call.  It also relies on	Perl's special "END"
       subroutines for termination when	it writes the raw profile to tmon.out.
       Under the standard command line Perl interpreter, these "END" blocks
       are run when the	"perl_run()" function is called.  Also,	Devel::DProf
       will not	profile	any code if it is inside a forked process.  Each time
       you run a Perl script from the command line, the	"perl_parse()" and
       "perl_run()" functions are called, Devel::DProf works just fine this
       way.

       Under mod_perl, the "perl_parse()" and "perl_run()" functions are
       called only once, when the parent server	is starting.  Any "END"	blocks
       encountered during server startup or outside of "Apache::Registry"
       scripts are suspended and run when the server is	shutdown via apache's
       child exit callback hook.  The parent server only runs Perl startup
       code, all request time code is run in the forked	child processes.  If
       you followed the	previous paragraph, you	should be able to see,
       Devel::DProf does not fit into the mod_perl model too well.  The
       Apache::DProf module exists to make it fit without modifying the
       Devel::DProf module or Perl itself.

       The Apache::DProf module	also requires apache version 1.3b3 or higher
       and "PerlChildInitHandler" enabled.  It is configured simply by adding
       this line to your httpd.conf file:

	PerlModule Apache::DProf

       When the	Apache::DProf module is	pulled in by the parent	server,	it
       will push a "PerlChildInitHandler" via the Apache push_handlers method.
       When a child server is starting the "Apache::DProf::handler" subroutine
       will called.  This handler will create a	directory "dprof/$$" relative
       to ServerRoot where Devel::DProf	will create it's tmon.out file.	 Then,
       the handler will	initialize the Perl debugger and pull in Devel::DProf
       who will	then install it's hooks	into the debugger and start it's
       profile timer.  The "END" subroutine installed by Devel::DProf will be
       run when	the child server is shutdown and the
       $ServerRoot/dprof/$$/tmon.out file will be generated and	ready for
       dprofpp.

       NOTE: $ServerRoot/logs/dprof/ will need to be writable by the user
       Apache is running as (i.e. nobody, apache, etc.).  If you can not write
       to $ServerRoot as this user, set	$ENV{APACHE_DPROF_PATH_ABSOLUTE} to an
       absolute	path of	a directory this user can.

AUTHOR
       Originally written by Doug MacEachern

       Currently maintained by Dirk Lindner <lze@cpan.org.org>

LICENSE
       This module is distributed under	the same terms as Perl itself.

SEE ALSO
       Devel::DProf(3),	Apache::DB(3), mod_perl(3), Apache(3)

perl v5.32.0			  2019-10-06		      Apache::DProf(3)

NAME | SYNOPSIS | DESCRIPTION | WHY | AUTHOR | LICENSE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Apache::DProf&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help