NAME
    Apache::VMonitor - Visual System and Apache Server Monitor

SYNOPSIS
      # Configuration in httpd.conf
      <Location /sys-monitor>
        SetHandler perl-script
        PerlHandler Apache::VMonitor
      </Location>

      # startup file or <Perl> section:
      use Apache::VMonitor();
      $Apache::VMonitor::Config{BLINKING} = 1;
      $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{NETLOAD}  = 1;
  
      @Apache::VMonitor::NETDEVS    = qw(lo eth0);
      $Apache::VMonitor::PROC_REGEX = join "\|", qw(httpd mysql squid);

DESCRIPTION
    This module emulates the reporting functionalities of top(), mount(),
    df() and ifconfig() utilities. It has a visual alert 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
        An indepth information about a single process is shown.

        If the chosen process is an Apache/mod_perl process, the following
        info is displayed:

        Process type (child or parent), status of the process (starting,
        reading, sending waiting and etc), how long the current request is
        processed or last was processed.

        Bytes transferred and requests served perl child and per slot.

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

        For all processes:

        General process info:

        UID, GID, State, TTY, Command line args

        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.

    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() it shows current date/time, machine uptime, average
        load, all the system CPU and memory usage: CPU Load, Mem and Swap
        usage.

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

           1) 5Mb < swap < 10 MB             color: light red
           2) 20% < swap (swapping is bad!)  color: red
           3) 70% < swap (swap almost used!) color: red + blinking

        Note that you can turn off blinking with:

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

        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() there is a report of the processes, but
        it shows all the relevant information about httpd processes only!
        The report includes the status of the process (starting, reading,
        sending waiting and 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 (only 64
        chars, as this is the maximum length stored by underlying Apache
        core library).

        At the end there is a calculation of the total memory being used by
        all httpd processes as reported by kernel, plus a result of an
        attempt to approximately calculate the real memory usage when
        sharing is in place. How do I calculate this:

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

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

        Please note that this might be incorrect for your system, so you use
        this number on your own risk. I have verified this number, by
        writing it down and then killing all the servers. The system memory
        went down by approximately this number. Again, use this number
        wisely!

        If you don't want the Apache 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 Apache/mod_perl processes section,
        displays the information in a top(1) fashion. You use a regular
        expression for processes you want to see.

        For each group of matched processes, just like with
        Apache/mod_processes a total size and estimation of the real memory
        taken into account the shared memory, is displayed.

        If you want the Apache section to be displayed a REGEX for processes
        to match. e.g if you want to see `http', `mysql' and `squid'
        processes, set:

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

        and

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

        The default is not to display this section.

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

        If you want the mount() 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() 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 filenodes 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 10% of free filenodes left. When that happens the
        filesystem related line will go bold and red and a mounting point
        will blink if the blinking is turned on. You can the blinking off
        with:

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

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

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

        The default is to display this section.

    ifconfig(1) emulation
        This section emulates the reporting capabilities of the ifconfig()
        utility. It reports how many packets and bytes were received and
        transmitted, their total, counts of errors and collisions, mtu size.
        in order to display this section you need to set two variables:

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

        and to set a list of net devices to report for, like:

          @Apache::VMonitor::NETDEVS  = qw(lo eth0);

        The default is NOT 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 /sys-monitor>
        SetHandler perl-script
        PerlHandler Apache::VMonitor
      </Location>

    The monitor will be displayed when you request
    http://localhost/sys-monitor or alike.

    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{BLINKING} = 1;
      $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;
      $Apache::VMonitor::Config{NETLOAD}  = 1;

    What net devices to display if $Apache::VMonitor::Config{NETLOAD} is ON:

      @Apache::VMonitor::NETDEVS  = qw(lo);

    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.

PREREQUISITES
    You need to have Apache::Scoreboard, Time::HiResand and GTop installed.
    And of course a running mod_perl enabled apache server.

BUGS
    Netload section reports negative bytes transferring when the numbers are
    very big, consider it a bug or a feature, but the problem is in the
    underlying libgtop library or GTop module and demands investigation.

TODO
    I want to include a report about open file handlers 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
    the Apache manpage, the mod_perl manpage, the Apache::Scoreboard
    manpage, the GTop manpage

AUTHORS
    Stas Bekman <sbekman@iname.com>

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

