'\"macro stdmacro
.\"
.\" Copyright (c) 1997 Silicon Graphics, Inc.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.TH WEBPINGVIS 1 "" "Performance Co-Pilot"
.SH NAME
\f3webpingvis\f1 \- visualize Web server response time
.\" literals use .B or \f3
.\" arguments use .I or \f2
.SH SYNOPSIS
\f3webpingvis\f1
[\f3\-CiVz\f1]
[\f3\-A\f1 \f2align\f1]
[\f3\-a\f1 \f2archive\f1]
[\f3\-h\f1 \f2host\f1]
[\f3\-m\f1 \f2max\f1]
[\f3\-n\f1 \f2pmnsfile\f1]
[\f3\-O\f1 \f2time\f1]
[\f3\-p\f1 \f2port\f1]
[\f3\-S\f1 \f2time\f1]
[\f3\-T\f1 \f2time\f1]
[\f3\-t\f1 \f2interval\f1]
[\f3\-x\f1 \f2version\f1]
[\f3\-Z\f1 \f2timezone\f1]
.SH DESCRIPTION
.B webpingvis
displays a summary of Web server response-time statistics
collected from the Performance Co-Pilot (PCP) infrastructure.
The display is modulated by the values of
performance metrics retrieved from the target
.I host
(which is running
.BR pmcd (1)
and the
.BR pmdawebping (1)
Performance Metrics Domain Agent) or
from the PCP archive log identified by
.IR archive .
The display is updated
every
.I interval
seconds (default 2 seconds).
.PP
As in all
.BR pmview (1)
scenes, when the mouse is moved over one of the bars,
the current value and metric information for that bar
will be shown in the text box near the top of the display.
The height of the bars is proportional to the
performance metric values relative to the maximum,
as controlled by size of the URLs being fetched by
.BR pmdawebping (1),
and the
.B \-m
option (see below).
.PP
The bars in the
.B webpingvis
scene represent the following information:
.TP 4
.B Size
The green bars indicate the relative sizes of the results returned
for each URL in the
.B pmdawebping
workload.
.TP 4
.B Response
For each URL in the
.B pmdawebping
workload, the components of the Web server response-time (connect, head
and body) and the total response-time is displayed.
.RS +4n
.PP
To the right, the component and total times are summed over all URLs in the
.B pmdawebping
workload.
.RE
.TP 4
.B Errors
The four red error bars indicate the number of socket, HTTP, HTML or other
errors that occurred in the last iteration of the
.B pmdawebping
workload.
Any of these errors will terminate the request for a URL.
.PP
.B webpingvis
uses
.BR pmview (1),
and so the user interface follows
that described for
.BR pmview (1),
which in turn displays the scene
within an
Inventor examiner viewer.
For generic control of the viewer, see
.BR ivview (1).
.PP
.B webpingvis
passes most command line options to
.BR pmview (1).
Therefore, the command line options
.BR \-A ,
.BR \-a ,
.BR \-C ,
.BR \-h ,
.BR \-n ,
.BR \-O ,
.BR \-p ,
.BR \-S ,
.BR \-t ,
.BR \-T ,
.BR \-x ,
.BR \-Z
and
.BR \-z ,
and the user interface are described in the
.BR pmview (1)
man page.
.PP
Options specific to
.B webpingvis
are:
.IP \f3\-i\f1
The URL names are not included as labels in the scene by default.
The
.B \-i
option forces them to be included.
.TP
.BI \-m " max"
Change the normalization factor for the response-time bars.
The value for
.I max
is in units of milliseconds, and should be the expected maximum value
for the total response-time aggregated over all URLs in the
.B pmdawebping
workload.  The default value is 1000 milliseconds.
.IP \f3\-V\f1
The derived configuration file for
.BR pmview (1)
is written on standard output.  This may be saved and used directly with
.BR pmview (1)
if the user wishes to customize the display, or modify some of
the normalization parameters.
.SH CAVEATS
As
.B webpingvis
sorts the configured URLs by size, running
.B webpingvis
shortly after starting
.BR pmdawebping (1)
may result in the URLs being sorted incorrectly as they may not have been
fetched.
.PP
The
.B ~
character may not be parsed correctly by
.BR pmview (1).
Therefore, if
.BR pmdawebping (1)
is fetching any URLs containing
.B ~
then
.B webpingvis
will not launch.
.SH FILES
.PD 0
.TP 10
.IR $PCP_VAR_DIR/pmns/ *
default PMNS specification files
.TP
.I $PCP_VAR_DIR/config/pmlogger/config.webpingvis
.BR pmlogger (1)
configuration file that can be used to create a PCP archive
suitable for display with
.B webpingvis
.TP
.I $PCP_VAR_DIR/config/pmchart/Web.Response
A
.BR pmchart (1)
configuration file for monitoring Web server response time
.PD
.SH "PCP ENVIRONMENT"
Environment variables with the prefix
.B PCP_
are used to parameterize the file and directory names
used by PCP.
On each installation, the file
.I /etc/pcp.conf
contains the local values for these variables.
The
.B $PCP_CONF
variable may be used to specify an alternative
configuration file,
as described in
.BR pcp.conf (4).
.SH SEE ALSO
.BR pmcd (1),
.BR pmchart (1),
.BR pmdawebping (1),
.BR pmdumplog (1),
.BR pminfo (1),
.BR pmlogger (1),
.BR pmval (1),
.BR pmview (1),
.BR weblogvis (1)
and
.BR webvis (1).