/ 
Apache-VMonitor-2.07
River stage zero No dependents
/ Apache::VMonitor

NAME

Apache::VMonitor - Visual System and Apache Server Monitor

SYNOPSIS

# mod_status should be compiled in (it is by default)
ExtendedStatus On

# Configuration in httpd.conf
<Location /system/vmonitor>
  SetHandler perl-script
  PerlHandler Apache::VMonitor
</Location>

# startup file or <Perl> section:
use Apache::VMonitor();
$Apache::VMonitor::Config{refresh}  = 0;
$Apache::VMonitor::Config{verbose}  = 0;
$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;
$Apache::VMonitor::Config{apache_sort_by}  = 'size';

$Apache::VMonitor::PROC_REGEX = join "\|", qw(httpd mysql squid);

DESCRIPTION

This module emulates the reporting functionalities of top(1), extended for mod_perl processes, mount(1), and df(1) utilities. It has a visual alerting capabilities and configurable automatic refresh mode. All the sections can be shown/hidden dynamically through the web interface.

The are two main modes:

  • Multi processes mode

    All system processes and information are shown. See the detailed description of the sub-modes below.

  • Single process mode

    If you need to get an indepth information about a single process, you just need to click on its PID.

    If the chosen process is a mod_perl process, the following info is displayed:

    • Process type (child or parent), status of the process (Starting, Reading, Sending, Waiting, etc.), how long the current request is processed or the last one was processed if the process is inactive at the moment of the report take.

    • How many bytes transferred so far. How many requests served per child and per slot.

    • CPU times used by process: total, utime, stime, cutime, cstime.

    For all (mod_perl and non-mod_perl) processes the following information is reported:

    • General process info: UID, GID, State, TTY, Command line arguments

    • Memory Usage: Size, Share, VSize, RSS

    • Memory Segments Usage: text, shared lib, date and stack.

    • Memory Maps: start-end, offset, device_major:device_minor, inode, perm, library path.

    • Loaded libraries sizes.

    Just like the multi-process mode, this mode allows you to automatically refresh the page on the desired intervals.

Other available modes within 'Multi processes mode'.

refresh mode

From within a displayed monitor (by clicking on a desired refresh value) or by setting of $Apache::VMonitor::Config{refresh} to a number of seconds between refreshes you can control the refresh rate. e.g:

$Apache::VMonitor::Config{refresh} = 60;

will cause the report to be refreshed every single minute.

Note that 0 (zero) turns automatic refreshing off.

top(1) emulation (system)

Just like top(1) it shows current date/time, machine uptime, average load, all the system CPU and memory usage: CPU load, Real memory and swap partition usage.

The top(1) section includes a swap space usage visual alert capability. The color of the swap report will be changed:

      swap usage               report color
---------------------------------------------------------
5Mb < swap < 10 MB             light red
20% < swap (swapping is bad!)  red
70% < swap (almost all used!)  red

The module doesn't alert when swap is being used just a little (<5Mb), since it happens most of the time, even when there is plenty of free RAM.

If you don't want the system section to be displayed set:

$Apache::VMonitor::Config{system} = 0;

The default is to display this section.

top(1) emulation (Apache/mod_perl processes)

Then just like in real top(1) there is a report of the processes, but it shows all the relevant information about mod_perl processes only!

The report includes the status of the process (Starting, Reading, Sending, Waiting, etc.), process' ID, time since current request was started, last request processing time, size, shared, virtual and resident size. It shows the last client's IP and Request URI (only 64 chars, as this is the maximum length stored by underlying Apache core library).

You can sort the report by any column, see the CONFIGURATION section for details.

The section is concluded with a report about the total memory being used by all mod_perl processes as reported by kernel, plus extra number, which results from an attempt to approximately calculate the real memory usage when memory sharing is taking place. The calculation is performed by using the following logic:

  1. For each process sum up the difference between shared and total memory.

  2. Now if we add the share size of the process with maximum shared memory, we will get all the memory that is actually used by all mod_perl processes, but the parent process.

Please note that this might be incorrect for your system, so you should use this number on your own risk. We have verified this number on the Linux OS, by taken the number reported by Apache::VMonitor, then stopping mod_perl and looking at the system memory usage. The system memory went down approximately by the number reported by the tool. Again, use this number wisely!

If you don't want the mod_perl processes section to be displayed set:

$Apache::VMonitor::Config{apache} = 0;

The default is to display this section.

top(1) emulation (any processes)

This section, just like the mod_perl processes section, displays the information in a top(1) fashion. To enable this section you have to set:

$Apache::VMonitor::Config{procs} = 1;

The default is not to display this section.

Now you need to specify which processes are to be monitored. The regular expression that will match the desired processes is required for this section to work. For example if you want to see all the processes whose name include any of these strings: http, mysql and squid, the following regular expression is to be used:

$Apache::VMonitor::PROC_REGEX = join "\|", qw(httpd mysql squid);
mount(1) emulation

This section reports about mounted filesystems, the same way as if you have called mount(1) with no parameters.

If you want the mount(1) section to be displayed set:

$Apache::VMonitor::Config{mount} = 1;

The default is NOT to display this section.

df(1) emulation

This section completely reproduces the df(1) utility. For each mounted filesystem it reports the number of total and available blocks (for both superuser and user), and usage in percents.

In addition it reports about available and used file inodes in numbers and percents.

This section has a capability of visual alert which is being triggered when either some filesystem becomes more than 90% full or there are less than 10% of free file inodes left. When this event happens the filesystem related report row will be displayed in the bold font and in the red color.

If you don't want the df(1) section to be displayed set:

$Apache::VMonitor::Config{fs_usage} = 0;

The default is to display this section.

abbreviations and hints

The monitor uses many abbreviations, which might be knew for you. If you enable the VERBOSE mode with:

$Apache::VMonitor::Config{verbose} = 1;

this section will reveal all the full names of the abbreviations at the bottom of the report.

The default is NOT to display this section.

CONFIGURATION

To enable this module you should modify a configuration in httpd.conf, if you add the following configuration:

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

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

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 the Basic or other authentication schemes provided by Apache and various extensions.

You can control the behavior of this module by configuring the following variables in the startup file or inside the <Perl> section.

Module loading:

use Apache::VMonitor();

Monitor reporting behavior:

$Apache::VMonitor::Config{refresh}  = 0;
$Apache::VMonitor::Config{verbose}  = 0;

Control over what sections to display:

$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;

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

$Apache::VMonitor::Config{apache_sort_by}  = 'size';

A regex to match processes for 'PROCS' section:

$Apache::VMonitor::PROC_REGEX = join "\|", qw(httpd mysql squid);

Read the DESCRIPTION section for a complete explanation of each of these variables.

DYNAMIC RECONFIGURATION

Apache::VMonitor allows you to dynamically turn on and off all the sections and enter a verbose mode that explains each section and the used abbreviations. These dynamic settings stored in the URI and not on the server side.

PREREQUISITES

Perl 5.6 or higher is required. If you are stuck with Perl 5.005 use the previous generation of this module. 0.8 is the latest version as of this writing and it's available from: http://www.cpan.org/authors/id/S/ST/STAS/Apache-VMonitor-0.8.tar.gz or your favorite CPAN mirror.

You need to have Apache::Scoreboard installed and configured in httpd.conf, which in turn requires mod_status to be installed. You also have to enable the extended status for mod_status, for this module to work properly. In httpd.conf add:

ExtendedStatus On

Notice that turning the ExtendedStatus mode On is not recommended for high-performance production sites, as it adds an overhead to the request response times.

You also need Time::HiRes to be installed

If you want process status information, you need GTop to be installed.

And of course you need a running mod_perl enabled apache server.

Subclassing

It should be trivial to subclass Apache::VMonitor. Just override tmpl_ and or data_ methods and off you go.

BUGS

Apache 2.0 doesn't have a complete scoreboard - access times are missing.

TODO

I want to include a report about open file handles per process to track file handlers leaking. It's easy to do that by just reading them from /proc/$pid/fd but you cannot do that unless you are root. libgtop doesn't have this capability - if you come up with solution, please let me know. Thanks!

SEE ALSO

Apache, mod_perl, Apache::Scoreboard, GTop

AUTHORS

Stas Bekman <stas@stason.org> Malcolm J Harwood <mjh-vmonitor@liminalflux.net>

COPYRIGHT

The Apache::VMonitor module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.