To run Apache::VMonitor, you need to have Apache::Scoreboard installed and configured in httpd.conf. Apache::Scoreboard, in turn, requires mod_status to be installed with ExtendedStatus enabled. In httpd.conf, add:

ExtendedStatus On

Turning on extended mode will add a certain overhead to each request's response time. If every millisecond counts, you may not want to use it in production.

You also need Time::HiRes and GTop to be installed. And, of course, you need a running mod_perl-enabled Apache server.

To enable Apache::VMonitor, add the following configuration to httpd.conf:

<Location /system/vmonitor>
    SetHandler perl-script
    PerlHandler Apache::VMonitor
</Location>

The monitor will be displayed when you request http://localhost/system/vmonitor/.

You probably want to protect this location from unwanted visitors. If you are accessing this location from the same IP address, you can use a simple host-based authentication:

<Location /system/vmonitor>
    SetHandler perl-script
    PerlHandler Apache::VMonitor
    order deny,allow
    deny  from all
    allow from 132.123.123.3
</Location>

Alternatively, you may use Basic or other authentication schemes provided by Apache and its extensions.

You should load the module in httpd.conf:

PerlModule Apache::VMonitor

or from the the startup file:

use Apache::VMonitor( );

You can control the behavior of Apache::VMonitor by configuring variables in the startup file or inside the <Perl>section. To alter the monitor reporting behavior, tweak the following configuration arguments from within the startup file:

$Apache::VMonitor::Config{BLINKING} = 1;
$Apache::VMonitor::Config{REFRESH}  = 0;
$Apache::VMonitor::Config{VERBOSE}  = 0;

To control what sections are to be displayed when the tool is first accessed, configure the following variables:

$Apache::VMonitor::Config{SYSTEM}   = 1;
$Apache::VMonitor::Config{APACHE}   = 1;
$Apache::VMonitor::Config{PROCS}    = 1;
$Apache::VMonitor::Config{MOUNT}    = 1;
$Apache::VMonitor::Config{FS_USAGE} = 1;

You can control the sorting of the mod_perl processes report by sorting them by one of the following columns: pid, mode, elapsed, lastreq, served, size, share, vsize, rss, client, or request. For example, to sort by the process size, use the following setting:

$Apache::VMonitor::Config{SORT_BY}  = "size";

As the application provides an option to monitor processes other than mod_perl processes, you can define a regular expression to match the relevant processes. For example, to match the process names that include "httpd_docs", "mysql", and "squid", the following regular expression could be used:

$Apache::VMonitor::PROC_REGEX = 'httpd_docs|mysql|squid';

We will discuss all these configuration options and their influence on the application shortly.