Use the 1.0 Vista Installation And Configuration Guide to install and configure Vista. Use the 2.0 Vista User's Guide to learn more about using the product. Although broken down into two major pieces, this help file is one html file, allowing for easier searches with the browser's Find command. Here is a complete outline of this docomument.

1.1 Introduction

The Vista - Performance Analysis Portal is an easy to use interface for creating and viewing plots using data gathered by the Capacity Data Collector. Since the Web Cruncher is web based, performance data can be shared or viewed anywhere. Read this guide to install and configure Vista. Although this document tries to be complete, the user will be much more prepared if familiar with Wham's Distributed Resource Monitor (DRM) and Capacity Data Collector (CDC) products.

The Capacity Data Collector (CDC) gathers data for and must be installed before installing Vista. For CDC installation instructions, please see the documentation for that product (CDC-guide.pdf).

These questions include:

1. What user would you like the web server to run as [wham]?
   Use an unprivileged user.
2. In what directory do you wish to install (a webcruncher directory will be appended to this path for you)?
   Full Path to the directory that will contain the webcruncher directory once the install is complete. if the directory /home/bdrake/ is given here, then Vista will be installed at /home/bdrake/webcruncher
3. Are you already collecting data with drm_hist out of cron? (Or do you already have a CDC data directory?)
   y or n. If yes to #3, there will be a question #3.5 prompting for the path to the directory holding the data.
4. Enter the hosts for which you wish to collect both system and process data, one at a time:
   Hostname (just enter if no more):
   If you are running drmd (the DRM agent) on some machines to collect system and process data, you may put their names one at a time here.
5. Enter the hosts for which you only wish to collect system data, one at a time:
   Hostname (just enter if no more):
   If you are running drmd on some machines to collect system data only, you may put their names one at a time here.
6. What is the fully qualified domain name of this machine?
   An IP address works here too.
7. On what port should the web server listen [80]?
   Only use a port less than 1024 if you have root access to start Apache.
8. What is the email address of the administrator of this tool?
   This email address will be used for any error messages.

Data collection, batch plot creation and data maintenance are all performed out of cron.

Here are the items that should be placed in the crontab:

1.3.2.1 Crontab Entry For Data Collection

For most configurations, running configWC should be sufficient. Perhaps you might want to collect data in 8 hour blocks or use already existing data with Vista. There are a few important conf files that allow for customization.

This file contains all settings used when executing drm_hist via the rundrmhist.sh script--another way to say when gathering data. Although the drm_hist GUI may be used to create this config file, a default is provided that is easily edited by hand. Hosts from which to collect data are listed here as well as the length of the sample to collect. The variables are:

BothHosts	Hosts collecting both system and process data
SysHosts	Hosts collecting only system data
DataSize	Maximum data size in bytes of raw data stored under the DataDir
DataRmSz	Data size to be removed to maintain the maximum data size
DataDir	Data directory, should be the same as the RAW_DIR in global.sh.
RunTime	Sample run time. The default is an hour. If wanting data for 2 Hour chunks or 8 hour chunks, this is the value to change.
Interval	Data sampling interval
SampPerInt	The Number of samples per interval time
ReportType	Data Report type
TopNumber	Top processes number--this many processes will be displayed in the drm_hist reports listing top CPU consumers, etc...
DestDir	Data Report Directory for daily spread sheet, can be the same as the RPT_DIR in global.sh.

httpd.conf is an Apache config file but is important to Vista since Vista is an Apache module built into the web server. Among other things, the web server's Port is specified in this file. Note that only root may start Apache for ports less than 1024. If installing WC to an NFS mounted drive, the LockFile directive should be uncommneted in this file to place the lock file on a local drive. If you do not do this, the parent httpd will exit with undefined results. see the comments in conf/httpd.conf.

For this example, pretend the domain name of the machine running Vista is fries.wham.com. Also assume that the web server has been started and is running on port 8001. Then from any browser, go to http://fries.wham.com:8001/. From there you may select the Interactive Data Viewer, Static Data Configurator, Static Data Viewer, or this Help page. Remember to replace fries.wham.com:8001 with the domain name or IP address (and port if not 80) of your newly installed Vista server.

1. You must have some data collected as discussed in these sections:
   1.3.2.1 Crontab Entry For Data Collection
   and 2.2 Storing Data For Vista.
   
2. You must have the right kind of data available for the metric. In other words, you can only see process data for existing processes, and you can only see process data from hosts that are collecting process data!
3. There must be data already collected that falls within your date time range.

If any of the above are FALSE, you will get a Plot Failed, plot was empty. message. Once data collection becomes regular, viewing plots is easy, since the Vista user knows when and what type of data is being collected.

Opera and Konqueror are not supported. All later versions of Netscape and IE are supported with one exception. IE 5.5 has a bug affecting javascript popup windows and is therefore NOT SUPPORTED. IE 5.5 users should switch to the latest greatest IE, move back to 5.0, or use Netscape.

Please report any bugs to Brett Drake or Adriane Sullivan. A current list of contacts is available at WHAM's Contacts Page.

If you want to see plots now, select the IDV and fill in the requested fields. To learn more about viewing plots on the fly, look at the Interactive Data Viewer help section. Thanks for using the1.0 Vista Installation And Configuration Guide! The2.0 Vista User's Guide is the remainder of this help file.

Vista's main components are the Interactive Data Viewer for defining and viewing data plots on the fly, the Static Data Configurator for defining plots to be created in batches, and the Static Data Viewer for viewing the batched plots.

To view a plot, go to the Interactive Data Viewer and fill in the requested fields.

The Host field contains all the hosts for which there is data. Just because a host is present, does not mean that the data you request must be present. For instance, a request could be made for process data for a nonexistent process. Furthermore, process data may not even be collected for that host (check the hist.conf configuration file). Finally, data may not exist for a certain date range. All of these problems generate a Plot Failed:Plot was empty. message.

Process ,Device, and Top Number fields are sometimes required depending on the metric. (BBD metric category here)

Note that drm_hist's TopNumber is not the default for this field! drm_hist's TopNumber relates to the CDC, whereas Vista's Top Number prompt relates only to the top plot that is currently being defined.

Begin and End are the starting and ending date and times, inclusive.

For viewing a plot spanning a year, a larger interval would be wise since this reduces the number of data points and produces a less cluttered graph. For plots that span minutes, a smaller interval would work best so that the plot has enough points to capture data at a finer level.

Note that data can only be generalized with the Sample Size field. If data with an Interval of 5 minutes is present, these data points are easily changed to 10 minute data. However, 10 minute data can not be made into 5 minute Data.

Plot Size may be Small (380x300 pixels), Medium (491x386 pixels), or Large (619x488 pixels).

Select Reset to clear all the fields.

The Add Column, Delete Column, Add Row, and Delete Row are used for defining multiple plots on a singe page. This feature is useful when needing to show multiple plots defined on the fly (as opposed to using the Static Data Viewer to show a group of the same plots generated in batches). Once you are looking at the necessary plots, bookmark the resulting URL for use later or cut, paste, and email it to a concerned party so that they can view your plots with a single click.

Select the Plot button after you have filled in all other fields.

The SDV looks for plots in the staticplots directory (SP_DIR from global.sh). The BBD batchplot program runs out of cron to generate the plots.

BATCH_DAY_START_HOUR="8"
BATCH_DAY_STOP_HOUR="18"
BATCH_SEVEN_DAY_WEEK="0"

Each run of drm_hist generates data resulting in the creation of one RunDir per host. Assume for this example that we have these values:

global.sh:

RAW_DIR="/usr/local/webcruncher/arch"

DataDir:
     /usr/local/webcruncher/arch
BothHosts:
     bigmac fries
RunTime:
     01:00:00

Then data would be collected and stored in

/usr/local/webcruncher/arch/bigmac/Run964443600

/usr/local/webcruncher/arch/fries/Run964443600