Looking Inside the Server (Practical mod

There are a number of tools that allow you look at the server internals at runtime, through a convenient web interface.

21.9.1. Apache::Status—Embedded Interpreter Status Information

This is a very useful module. It lets you watch what happens to the Perl part of the mod_perl server. You can watch the size of all subroutines and variables, variable dumps, lexical information, opcode trees, and more.

You shouldn't use it on a production server, as it adds quite a bit of overhead for each request.

21.9.1.1. Minimal configuration

This configuration enables the Apache::Status module with its minimum feature set. Add this to httpd.conf:

<Location /perl-status>
    SetHandler perl-script
    PerlHandler Apache::Status
</Location>

If you are going to use Apache::Status it's important to put it as the first module in the startup file, or in httpd.conf:

# startup.pl
use Apache::Status ( );
use Apache::Registry ( );
use Apache::DBI ( );

For example, if you use Apache::DBI and you don't load Apache::Status before Apache::DBI, you will not get the Apache::DBI menu entry (which allows you to see persistent connections).

21.9.1.2. Extended configuration

There are several variables you can use to modify the behavior of Apache::Status:

PerlSetVar StatusOptionsAll On: This single directive will enable all of the options described below.
PerlSetVar StatusDumper On: When you are browsing symbol tables, you can view the values of your arrays, hashes, and scalars with Data::Dumper.
PerlSetVar StatusPeek On: With this option On and the Apache::Peek module installed, functions and variables can be viewed in Devel::Peekstyle.
PerlSetVar StatusLexInfo On: With this option On and the B::LexInfo module installed, subroutine lexical variable information can be viewed.
PerlSetVar StatusDeparse On: With this option On and B::Deparse version 0.59 or higher (included in Perl 5.005_59+), subroutines can be "deparsed." Options can be passed to B::Deparse::new like so:

PerlSetVar StatusDeparseOptions "-p -sC"

See the B::Deparse manpage for details.
PerlSetVar StatusTerse On: With this option On, text-based optree graphs of subroutines can be displayed, thanks to B::Terse.
PerlSetVar StatusTerseSize On: With this option On and the B::TerseSize module installed, text-based optree graphs of subroutines and their sizes can be displayed. See the B::TerseSize documentation for more info.
PerlSetVar StatusTerseSizeMainSummary On: With this option On and the B::TerseSize module installed, a "Memory Usage" submenu will be added to the Apache::Status main menu. This option is disabled by default, as it can be rather CPU-intensive to summarize memory usage for the entire server. It is strongly suggested that this option be used only with a development server running in -X mode, as the results will be cached.

Remember to preload B::TerseSize in httpd.conf and make sure that it's loaded after Apache::Status:

PerlModule Apache::Status PerlModule B::Terse
PerlSetVar StatusGraph On: When StatusDumper (see above) is enabled, another submenu, "OP Tree Graph," will be present with the dump if this configuration variable is set to On.

This requires the B module (part of the Perl compiler kit) and the B::Graph module, Version 0.03 or higher, to be installed along with the dot program. dot is part of the graph-visualization toolkit from AT&T (http://www.research.att.com/sw/tools/graphviz/).

WARNING: Some graphs may produce very large images, and some graphs may produce no image if B::Graph's output is incorrect.

There is more information about Apache::Status in its manpage.

21.9.1.3. Usage

Assuming that your mod_perl server is listening on port 81, fetch http://www.example.com:81/perl-status:

Embedded Perl version v5.6.1 for Apache/1.3.17 (Unix) mod_perl/1.25
process 9943, running since Fri Feb 9 17:48:50 2001

All the sections below are links when you view them through /perl-status:

Perl Configuration
Loaded Modules
Inheritance Tree
Enabled mod_perl Hooks
Environment
PerlRequire'd Files
Signal Handlers
Symbol Table Dump
ISA Tree
Compiled Registry Scripts

Here's what these sections show:

Perl Configuration is the same as the output from perl -V (loaded from Config.pm).
Loaded Modules shows the loaded Perl modules.
Inheritance Tree shows the inheritance tree of the loaded modules.
Enabled mod_perl Hooks shows all mod_perl hooks that were enabled at compile time.
Environment shows the contents of %ENV.
PerlRequire'd Files displays the files that were required via PerlRequire.
Signal Handlers shows the status of all signal handlers (using %SIG).
Symbol Table Dump shows the symbol table dump of all packages loaded in the process—you can click through the symbols and, for example, see the values of scalars, jump to the symbol dumps of specific packages, and more.
ISA Tree shows the ISA inheritance tree.
Compiled Registry Scripts shows Apache::Registry, Apache::PerlRun, and other scripts compiled on the fly.

From some menus you can move deeper to peek into the internals of the server, to see the values of the global variables in the packages, to see the cached scripts and modules, and much more. Just click around.

Remember that whenever you access /perl-status you are always inside one of the child processes, so you may not see what you expect, since this child process might have a different history of processed requests and therefore a different internal state. Sometimes when you fetch /perl-status and look at the Compiled Registry Scripts section you see no listing of scripts at all. Apache::Statusshows the registry scripts compiled in the httpd child that is serving your request for /perl-status; if the child has not yet compiled the requested script, /perl-status will just show you the main menu.

21.9.2. mod_status

The mod_status module allows a server administrator to find out how well the server is performing. An HTML page is presented that gives the current server statistics in an easily readable form. If required, given a compatible browser, this page can be automatically refreshed. Another page gives a simple machine-readable list of the current server state.

This Apache module is written in C. It is compiled by default, so all you have to do to use it is enable it in your configuration file:

<Location /status>
    SetHandler server-status
</Location>

For security reasons you will probably want to limit access to it. If you have installed Apache according to the instructions given in this book, you will find a prepared configuration section in httpd.conf. To enable use of the mod_status module, just uncomment it:

ExtendedStatus On
<Location /status>
    SetHandler server-status
    Order deny,allow
    Deny from all
    Allow from localhost
</Location>

You can now access server statistics by using a web browser to access the page http://localhost/status (as long as your server recognizes localhost).

The details given by mod_status are:

The number of children serving requests
The number of idle children
The status of each child, the number of requests that child has performed and the total number of bytes served by the child
The total number of accesses and the total bytes served
The time the server was last started/restarted and for how long it has been running
Averages giving the number of requests per second, the number of bytes served per second, and the number of bytes per request
The current percentage of the CPU being used by each child and in total by Apache
The current hosts and requests being processed

In Chapter 5 you can read about Apache::VMonitor, which is a more advanced sibling of mod_status.

Turning the ExtendedStatus mode on is not recommended for high-performance production sites, as it adds overhead to the request response times.

21.9. Looking Inside the Server

21.9.1. Apache::Status—Embedded Interpreter Status Information

21.9.1.1. Minimal configuration

21.9.1.2. Extended configuration

21.9.1.3. Usage

21.9.2. mod_status