Performance Co-Pilot Weblog PMDA for Monitoring of Web Server logs
==================================================================

This PMDA is capable of monitoring the activity of multiple Web servers,
in terms of requests and bytes, in real time. The PMDA can also monitor
proxy server, SOCKS server and ftpd logs.

Site configuration is discussed in the online HTML documentation located
at $PCP_DOC_DIR/pcpweb. This should be read before proceeding any further
with installing this PMDA. The file $PCP_DOC_DIR/pcpweb/README contains
instructions for installing this documentation.

During the installation process, you may be prompted for several 
parameters which will affect the behavior of the weblog PMDA. These
are discussed in the pmdaweblog(1) man page.


Installation of the Weblog PMDA
===============================

1. Check that there is no clash with the Performance Metrics Domain
   number defined in domain.h and the other PMDAs currently in use
   (see $PCP_PMCDCONF_PATH).  If there is, edit domain.h and choose
   another domain number.

2. Ensure that the web server control files can be correctly located as
   follows.

   Web Server	Default Directory	Environment	Search for Config
   Type					Variable	File(s) and/or Logs
							Below the Default
							Directory

   Netscape	/usr/ns-home		$NSROOTPATH	httpd-*/obj.conf
		and					httpd-*/magnus.conf
		/var/netscape/suitespot			https-*/obj.conf
							https-*/magnus.conf
							proxy-*/obj.conf
							proxy-*/magnus.conf

   Netscape	/usr/ns-home		$NSROOTPATH	proxy-server/logs/sockd
   Proxy

   Netscape	/var/ns-proxy		$NSPROXYPATH	logs/access
   Proxy						logs/errors
							logs/sockd

   Outbox	/var/www/htdocs/outbox	$OUTBOXPATH	logs/access
							logs/errors

   NCSA		/var/www		$NCSAPATH	server/logs/access_log
							server/logs/error_log

   Zeus		/usr/local/zeus		$ZEUSPATH	server.ini
							log/transfer
							log/errors

   Apache	/usr/apache		$APACHEPATH	conf/httpd.conf
							conf/srm.conf
							log/access_log
							log/error_log

   Anon FTP	/etc/passwd		$PASSWDPATH	[file, not dir] for ~ftp
		/var/adm/SYSLOG		$SYSLOGPATH	[file, not dir] for
							access and errors

   To over-ride the Default Directory for a particular type of Web
   server, set the corresponding Environment Variable to the absolute
   pathname of the directory.  As a special case $NSROOTPATH for the
   non-proxy Netscape Web server can be set to a colon (:) separated
   list of directory names to be searched (in the style of the $PATH
   for /bin/sh).


3. Then run the Install script (as root)

	# cd $PCP_PMDAS_DIR/weblog
	# ./Install

4. The installation script will prompt if this is a collector and/or
   monitor installation.  Briefly:

   o if there are Web servers on this host, then this is a collector host.

   o if monitoring tools (pmchart(1), pmlogger(1) etc.) will be run on
     this host, then this is a monitoring host.

   Consult the HTML documentation for more details.  A monitoring host
   installation will install only the namespace and some application
   configuration files.

5. The next prompt will ask if this is a default installation.  The
   default installation will search for known Web server configurations
   and install the PMDA to monitor any logs that are found.  This is
   appropriate for first time installations.  The non-default
   installation is described in points 6 to 8.

6. The configuration file for the weblog PMDA must be found and
   checked.  The Install script will look in the likely places for an
   existing file and prompt for confirmation. Otherwise, a
   configuration file can be automatically generated by searching known
   Web server configuration files and directories.

7. The second stage of the Install script prompts for the pmdaweblog(1)
   parameters. The default values should be adequate for an initial
   installation.

8. The final stage will install the agent and restart PMCD (the
   Performance Metrics Collection Daemon). The Install script should
   report that the Metrics are OK.


De-installation
===============

Simply use (as root)

	# cd $PCP_PMDAS_DIR/weblog
	# ./Remove


Changing the settings
=====================

The safest way to alter any settings that were entered in the Install
script is to re-run the Install script. Changes to the weblog.conf file
can be also be registered by running the Install script.

To quickly test changes to the configuration files, the agent and pmcd
can be restarted as follows:

    To register any changes made to the weblog.conf file, the agent
    must be killed and restarted:

	# pmsignal -a -s KILL pmdaweblog
	# pmsignal -a -s HUP pmcd

    To register any changes to the $PCP_PMCDCONF_PATH file you must
    restart PMCD:

	# $PCP_RC_DIR/pcp start


Troubleshooting
===============

0. If there is trouble locating the Web server access and error logs,
   try running the server.sh script with diagnostics:

	$ cd $PCP_PMDAS_DIR/weblog
	$ ./server.sh -q -v </dev/null

1. After installing or restarting the agent, the PMCD log file
   ($PCP_LOG_DIR/pmcd/pmcd.log) and the PMDA log file
   ($PCP_LOG_DIR/pmcd/weblog.log) should be checked for any warnings
   or errors.

2. If the Install script reports some warnings when checking the
   metrics, the problem should be listed in one of the log files.

3. If the PMDA is configured to look at the correct access logs, and
   the Web server is demonstrably updating those access logs, but the
   exported performance metrics are not being updated, then the problem
   may be in the pattern matching.  To diagnose this:

   Find the corresponding "server" line in
   $PCP_VAR_DIR/config/web/weblog.conf, e.g.

   server ha2.melbourne.sgi.com:80 on \
       CERN /usr/ns-home/httpd-ha2/logs/access \
       CERN_err /usr/ns-home/httpd-ha2/logs/errors

   the pattern is symbolicly named after the word "on" (CERN above) and
   the path to the access log follows
   (/usr/ns-home/httpd-ha2/logs/access above).  These two are used as
   the last two arguments to check_match below:

	$ cd $PCP_PMDAS_DIR/weblog
	$ ./check_match $PCP_VAR_DIR/config/web/weblog.conf \
		CERN /usr/ns-home/httpd-ha2/logs/access

   If things are working OK, expect to see lines like:

   [1] match: method="GET" size="17198"
   [2] match: method="GET" size="-"
   [3] match: method="GET" size="27102"
   [4] match: method="POST" size="4503"
   [5] match: method="HEAD" size="-"

   If this does not happen, you need to review the format of the lines
   in the access logs and modify the pattern by reference to the
   regcmp(3) man page.

4. Additional information can be logged if there appears to be problems
   with the monitoring of server log files. Running the Install script
   with the -D flag will add a prompt for a debugging flag. This can be
   a combination of bits given by pmdbg -l:

	# pmdbg -l

   The application flags will cause the PMDA to report additional
   information in $PCP_LOG_DIR/pmcd/weblog.log. DBG_TRACE_APPL0 reports
   the least information and DBG_TRACE_APPL2 may report too much if the
   server is handling many requests.