META: needs more organization (if you grok any of the following,
patches are welcome)

META: there is a new compile-time option in perl-5.8.8+: -DDEBUG_LEAKING_SCALARS,
which prints out the addresses of leaked SVs and new_SV() can be used to discover where those SVs were allocated.
(see perlhack.pod for more info)

META: profiling: need a new entry of profiling.
+ running mod_perl under gprof: Defining GPROF when compiling uses the moncontrol() function to disable gprof profiling in the parent,
and enable it only for request processing in children (or in one_process mode).

META: Jeff Trawick wrote a few useful debug modules,
for httpd-2.1: mod_backtrace (similar to bt in gdb,
but doesn't require the core file) and mod_whatkilledus (gives the info about the request that caused the segfault).
http://httpd.apache.org/~trawick/exception_hook.html

If mod_perl is built as a DSO module, you cannot set the breakpoint in the mod_perl source files when the httpd program gets loaded into the debugger. The reason is simple: At this moment httpd has no idea about mod_perl module yet. After the configuration file is processed and the mod_perl DSO module is loaded then the breakpoints in the source of mod_perl itself can be set.

The trick is to break at apr_dso_load, let it load libmodperl.so, then you can set breakpoints anywhere in the modperl code:

When the server is started under gdb, it first loads the symbol tables of the dynamic libraries that it sees going to be used. Some versions of gdb may take ages to complete this task, which makes the debugging very irritating if you have to restart the server all the time and it doesn't happen immediately.

The trick is to set the auto-solib-add flag to 0:

set auto-solib-add 0

as early as possible in ~/.gdbinit file.

With this setting in effect, you can load only the needed dynamic libraries with sharedlibrary gdb command. Remember that in order to set a breakpoint and step through the code inside a certain dynamic library you have to load it first. For example consider this gdb commands file:

This script stops in modperl_hook_init(), so you can step through the mod_perl startup. We had to use the ap_run_pre_config so we can load the libmodperl.so library as explained earlier. Since httpd restarts on the start, we have to continue until we hit modperl_hook_init second time, where we can set the breakpoint at apr_poll, the very point where httpd polls for new request and run again continue so it'll stop at apr_poll. This particular script passes over modperl_hook_init(), since we run the continue command a few times to reach the apr_poll breakpoint. See the Precooked gdb Startup Scripts section for standalone script examples.

When gdb stops at the function apr_poll it's a time to start the client, that will issue a request that will exercise the server execution path we want to debug. For example to debug the implementation of APR::Pool we may run:

% t/TEST -run apr/pool

which will trigger the run of a handler in t/response/TestAPR/pool.pm which in turn tests the APR::Pool code.

But before that if we want to debug the server response we need to set breakpoints in the libraries we want to debug. For example if we want to debug the function PerlIOAPR_open which resides in APR/PerlIO/PerlIO.so we first load it and then we can set a breakpoint in it. Notice that gdb may not be able to load a library if it wasn't referenced by any of the code. In this case we have to load this library at the server startup. In our example we load:

PerlModule APR::PerlIO

in httpd.conf. To check which libraries' symbol tables can be loaded in gdb, run (when the server has been started):

gdb> info sharedlibrary

which also shows which libraries are loaded already.

Also notice that you don't have to type the full path of the library when trying to load them, even a partial name will suffice. In our commands file example we have used sharedlibrary mod_perl instead of saying sharedlibrary mod_perl.so.

If you want to set breakpoints and step through the code in the Perl and APR core libraries you should load their appropriate libraries:

Setting auto-solib-add to 0 makes the debugging process unusual, since originally gdb was loading the dynamic libraries automatically, whereas now it doesn't. This is the price one has to pay to get the debugger starting the program very fast. Hopefully the future versions of gdb will improve.

Just remember that if you try to step-in and debugger doesn't do anything, that means that the library the function is located in wasn't loaded. The solution is to create a commands file as explained in the beginning of this section and craft the startup script the way you need to avoid extra typing and mistakes when repeating the same debugging process again and again.

Under threaded mpms (e.g. worker), it's possible that you won't be able to debug unless you tell gdb to load the symbols from the threads library. So for example if on your OS that library is called libpthread.so make sure to run:

Another important thing is that whenever you want to be able to see the source code for the code you are stepping through, the library or the executable you are in must have the debug symbols present. That means that the code has to be compiled with -g option for the gcc compiler. For example if I want to set a breakpoint in /lib/libc.so, I can do that by loading:

gdb> sharedlibrary /lib/libc.so

But most likely that this library has the debug symbols stripped off, so while gdb will be able to break at the breakpoint set inside this library, you won't be able to step through the code. In order to do so, recompile the library to add the debug symbols.

If debug code in response handler you usually start the client after the server was started, when doing this a lot you may find it annoying to need to wait before the client can be started. Therefore you can use a few tricks to do it in one command. If the server starts fast you can use sleep():

Here are a few startup scripts you can use with gdb to accomplish one of the common debugging tasks. To execute the startup script, simply run:

% gdb -command=.debug-script-filename

They can be run under gdb and any of the gdb front-ends. For example to run the scripts under ddd substitute gdb with ddd:

% ddd -command=.debug-script-filename

Debugging mod_perl Initialization

The code/.debug-modperl-init startup script breaks at the modperl_hook_init() function, which is useful for debugging code at the modperl's initialization phase.

Debugging mod_perl's Hooks Registeration With httpd

Similar to the previous startup script, the code/.debug-modperl-register startup script breaks at the modperl_register_hooks(), which is the very first hook called in the mod_perl land. Therefore use this one if you need to start debugging at an even earlier entry point into mod_perl.

Refer to the notes inside the script to adjust it for a specific httpd.conf file.

Debugging mod_perl XS Extensions

The code/.debug-modperl-xs startup script breaks at the mpxs_Apache2__Filter_print() function implemented in xs/Apache2/Filter/Apache2__Filter.h. This is an example of debugging code in XS Extensions. For this particular example the complete test case is:

When filter/api test is running it calls mpxs_Apache2__Filter_print() which is when the breakpoint is reached.

Debugging code in shared objects created by Inline.pm

This is not strictly related to mod_perl, but sometimes when trying to reproduce a problem (e.g. for a p5p bug-report) outside mod_perl, the code has to be written in C. And in certain cases, Inline can be just the right tool to do it quickly. However if you want to interactively debug the library that it creates, it might get tricky. So similar to the previous sections, here is a gdb code/.debug-inline startup script that will save you a lot of time. All the details and a sample perl script are inside the gdb script.

When your application dies with the Segmentation fault error (which is generated by the SIGSEGV signal) and optionally generates a core file you can use gdb or a similar debugger to find out what caused the Segmentation fault (or a segfault as we often call it).

In order to debug the core file you may need to recompile Perl and mod_perl with debugging symbols. Usually you have to recompile only mod_perl, but if the core dump happens in the libperl.so library and you want to see the whole backtrace, you need to recompile Perl as well. It may also occur inside httpd or 3rd party module, in which case you will need to recompile those. The following notes should help to accomplish the right thing:

mod_perl

rebuild mod_perl with MP_DEBUG=1.

% perl Makefile.PL MP_DEBUG=1 ...
% make && make test && make install

Building mod_perl with PERL_DEBUG=1 will:

add -g to EXTRA_CFLAGS

turn on MP_TRACE (tracing)

Set PERL_DESTRUCT_LEVEL=2

Link against libperld.so if $Config{archlibexp}/CORE/libperld$Config{lib_ext} exists.

httpd

If the segfault happens inside ap_ or apr_ calls, rebuild httpd with --enable-maintainer-mode:

if the trace happens in one of the 3rd party perl modules, make sure to rebuild them, now that you've perl re-built with debugging flags. They will automatically pick the right compile flags from perl.

Now let's get the core file dumped from within the mod_perl server. Sometimes the program aborts abnormally via the SIGSEGV signal (Segmentation Fault), but no core file is dumped. And without the core file it's hard to find the cause of the problem, unless you run the program inside gdb or another debugger in first place. In order to get the core file, the application has to:

have the effective UID the same as real UID (the same goes for GID). Which is the case of mod_perl unless you modify these settings in the program.

be running from a directory which at the moment of the Segmentation fault is writable by the process that received this signal. Notice that the program might change its current directory during its run, so it's possible that the core file will need to be dumped in a different directory from the one the program was originally started from.

Under Apache ServerRoot is used as the default directory. Since that directory is sually not writable by the user running Apache, it's possible to use the directive CoreDumpDirectory (available since Apache 2.0.45) to tell Apache to dump the core file elsewhere.

be started from a shell process with sufficient resource allocations for the core file to be dumped. You can override the default setting from within a shell script if the process is not started manually. In addition you can use BSD::Resource to manipulate the setting from within the code as well.

You can use ulimit for bash and limit for csh to check and adjust the resource allocation. For example inside bash, you may set the core file size to unlimited:

panic% ulimit -c unlimited

or for csh:

panic% limit coredumpsize unlimited

For example you can set an upper limit on the core file size to 8MB with:

panic% ulimit -c 8388608

So if the core file is bigger than 8MB it will be not created.

Of course you have to make sure that you have enough disk space to create a big core file (mod_perl core files tend to be of a few MB in size).

Note that when you are running the program under a debugger like gdb, which traps the SIGSEGV signal, the core file will not be dumped. Instead it allows you to examine the program stack and other things without having the core file.

In this script we load the Apache2::RequestRec, Apache2::RequestIO, Debug::DumpCore and Cwd modules, then we acquire the Apache request object and set the HTTP response header. Now we come to the real part -- we get the current working directory, print out the location of the core file that we are about to dump and finally we call Debug::DumpCore::segv() which dumps the core file.

Before we run the script we make sure that the shell sets the core file size to be unlimited, start the server in single server mode as a non-root user and generate a request to the script:

Well, you can see the last commands, but our perl and mod_perl are probably without the debug symbols. This is not the kind of trace you should send as a part of your bug report, because a lot of important information that should aid resolve the reported problem is missing.

Therefore the next step is to recompile Perl and mod_perl (and may be Apache) with debug symbols as explained earlier in this chapter.

Now when we repeat the process of starting the server, issuing a request and getting the core file, after which we run gdb again against the executable and the dumped core.6789 file.

Reading the trace from bottom to top, we can see that it starts with Apache calls, followed by mod_perl calls which end up in modperl_callback() which calls the Perl program via Perl_call_sv.

Notice that in our example we knew what script has caused the Segmentation fault. In a real world the chances are that you will find the core file without any clue to which of handler or script has triggered it. The special curinfogdb macro comes to help:

Simply past the correct version at the gdb prompt (in this example the perl is threaded):

(gdb) define curinfo
Type commands for definition of "curinfo".
End with a line saying just "end".
> printf "%d:%s\n", my_perl->Tcurcop->cop_line, \
my_perl->Tcurcop->cop_file
>end

and now we can call it:

(gdb) curinfo
No symbol "my_perl" in current context.

Oops, the function where the segfault has happened doesn't have the perl context, so we need to look at the backtrace and find the first function which accepts the my_perl argument (this is because we use a threaded perl). In this example this is the second frame:

Et voilà, we can see that the segfault was triggered on line 14 of core_dump.pl, which has the line:

Debug::DumpCore::segv();

And we are done.

These are the bits of information that are important to extract and include in your bug report in order for us to be able to reproduce and resolve a problem. In this example it was the full backtrace, the filename and line where the faulty function was called (the faulty function is Debug::DumpCore::segv()) and the actual line where the Segmentation fault occured (crash_now_for_real at DumpCore.xs:10).

If the core file(s) are found in the mod_perl source directory, when running t/REPORT the core file backtraces will be automatically extracted and added to the report if the perl module Devel::GDB is installed.

See the function dump_core_file() in Apache-Test/lib/Apache/TestReport.pm if you want to see how it is invoked or refer to the Devel::GDB manpage.

There are two ways to get core files under Solaris. The first is by configuring the system to allow core dumps, the second is by stopping the process when it receives the SIGSEGV signal and "manually" obtaining the core file.

By default, Solaris 8 won't allow a setuid process to write a core file to the file system. Since apache starts as root and spawns children as 'nobody', core dumps won't produce core files unless you modify the system settings.

To see the current settings, run the coreadm command with no parameters and you'll see:

These settings are stored in the /etc/coreadm.conf file, but you should set them with the coreadm utility. As super-user, you can run coreadm with -g to set the pattern and path for core files (you can use a few variables here) and -e to enable some of the disabled items. After setting a new pattern, enabling global, global-setid, and log, and rebooting the system (reboot is required), the new settings look like:

Now you'll start to see core files in the designated cores directory and they will look like core.httpd.2222 where httpd is the name of the executable and the 2222 is the process id. The new core files will be read/write for root only to maintain some security, and you should probably do this on development systems only.

Watch the error_log file for reaped processes, as when they get SISSEGV signals. When the process is reaped it's stopped but not killed.

Use gcore(1) to get a core of stopped process or attach to it with gdb(1). For example if the process id is 662:

panic% gcore 662
gcore: core.662 dumped

Now you can load this core file in gdb(1).

kill -9 the stopped process. Kill the truss(1) processes as well, if you don't need to trap other segfaults.

Obviously, this isn't great to be doing on a production system since truss(1) stops the process after it dumps core and prevents Apache from reaping it. So, you could hit the clients/threads limit if you segfault a lot.

Apache 2.0 source comes with a nice pack of macros and can be found in httpd-2.0/.gdbinit. To use it issue:

gdb> source /wherever/httpd-2.0/.gdbinit

Now if for example you want to dump the contents of the bucket brigade, you can do:

gdb> dump_brigade my_brigade

where my_brigade is the pointer to the bucket brigade that you want to debug.

mod_perl 1.0 has a similar file (modperl/.gdbinit) mainly including handy macros for dumping Perl datastructures, however it works only with non-threaded Perls. But otherwise it's useful in debugging mod_perl 2.0 as well.

Perl, mod_perl and httpd C code makes an extensive use of C macros, which sometimes use many other macros in their definitions, so it becomes quite a task to figure out how to figure out what a certain macro expands to, especially when the macro expands to different values in differnt environments. Luckily there are ways to automate the expansion process.

The mod_perl Makefile's include a rule for macro expansions which you can find by looking for the c.i. rule. To expand all macros in a certain C file, you should run make filename.i, which will create filename.i with all macros expanded in it. For example to create apr_perlio.i with all macros used in apr_perlio.c:

For each library that you want to use this feature with you have to compile it with:

CFLAGS="-gdwarf-2 -g3"

or whatever is appropriate for your system, refer to the gcc manpage for more info.

To compile perl with this debug feature, pass -Doptimize='-gdwarf-2 -g3' to ./Configure. For Apache run:

CFLAGS="-gdwarf-2 -g3" ./configure [...]

for mod_perl you don't have to do anything, as it'll pick the $Config{optimize} Perl flags automatically, if Perl is compiled with -DDEBUGGING (which is implied on most systems, if you use -Doptimize='-g' or similar.)

Notice that this will make your libraries huge! e.g. on Linux 2.4 Perl 5.8.0's normal libperl.so is about 0.8MB on linux, compiled with -Doptimize='-g' about 2.7MB and with -Doptimize='-gdwarf-2 -g3' 12.5MB. httpd is also becomes about 10 times bigger with this feature enabled. mod_perl.so instead of 0.2k becomes 11MB. You get the idea. Of course since you may want this only during the development/debugging, that shouldn't be a problem.