NAME
pmdashping - "shell-ping" performance metrics domain agent
SYNOPSIS
$PCP_PMDAS_DIR/shping/pmdashping [-C] [-d domain] [-l log
file] [-I interval] [-t timeout] configfile
DESCRIPTION
pmdashping is a Performance Metrics Domain Agent (PMDA)
which exports quality of service and response time mea
surements for arbitrary commands as might be run from a
shell such as sh(1).
These measurements are intended to be used to quantify
service quality and service availability for those ser
vices that are either mission critical or act as early
indicators of adverse system performance.
The sample configuration monitors simple shell commands
(exit and date(1)), a short computationally intensive task
using sum(1), a short C compilation, DNS lookup via
nslookup(1), YP lookup via ypcat(1), bind/portmapper ser
vice using rpcbind(1), SMTP by connecting to telnet port
25 and sending an ``expn root'' request, and NNTP by con
necting to telnet port 119 and running a ``listgroup''
command.
It is expected that other commands would follow the exam
ples in the sample configuration file, and most deploy
ments of the pmdashping PMDA are expected to use a cus
tomized configuration file.
A brief description of the pmdashping command line options
follows:
-C Parse configfile, reporting any errors and exiting
with non-zero status if the file contains syntactical
errors.
-d It is absolutely crucial that the performance metrics
domain number specified here is unique and consis
tent. That is, domain should be different for every
PMDA on the one host, and the same domain number
should be used for the same PMDA on all hosts.
-l Location of the log file. By default, a log file
named shping.log is written in the current directory
of pmcd(1) when pmdashping is started, i.e.
$PCP_LOG_DIR/pmcd. If the log file cannot be created
or is not writable, output is written to the standard
error instead.
tions of the list of commands provided via the con
figuration file configfile. The default is 2 min
utes.
-t Amount of time (in seconds) to wait before timing out
awaiting a response for a command from configfile.
The default is 20 seconds.
The required configfile specifies ``tag'' and ``command''
pairs, each on a separate line. All of the commands are
run one after another, with the whole group rescheduled to
be run once per interval. For each command that is run,
pmdashping records information related to the success (or
timeout), exit status, elapsed time and CPU time (system
and user), and this information is exported by the PMDA.
The tags are used to identify the individual commands
amongst the values exported by the PMDA, and form the
external instance domain identifiers for the pmdashping
metrics which relate to each command.
INSTALLATION
In order for a host to export the names, help text and
values for the shping performance metrics, do the follow
ing as root:
# cd $PCP_PMDAS_DIR/shping
# ./Install
The set of ``tag'' and ``command'' pairs may be specified
from a default (sample) configuration file, a customized
file or entered interactively as part of the Install
script.
If you want to undo the installation, do the following as
root:
# cd $PCP_PMDAS_DIR/shping
# ./Remove
pmdashping is launched by pmcd(1) and should never be exe
cuted directly. The Install and Remove scripts notify
pmcd(1) when the agent is installed or removed.
FILES
$PCP_PMCDCONF_PATH
command line options used to launch pmdashping
$PCP_PMDAS_DIR/shping/help
default help text file for the shping metrics
$PCP_PMDAS_DIR/shping/sample.conf
example configuration file with a number of com
mon commands
installation script for the pmdashping agent
$PCP_PMDAS_DIR/shping/Remove
undo installation script for pmdashping
$PCP_LOG_DIR/pmcd/shping.log
default log file for error messages and other
information from pmdashping
PCP ENVIRONMENT
Environment variables with the prefix PCP_ are used to
parameterize the file and directory names used by PCP. On
each installation, the file /etc/pcp.conf contains the
local values for these variables. The $PCP_CONF variable
may be used to specify an alternative configuration file,
as described in pcp.conf(4).
SEE ALSO
pmcd(1) and pmgshping(1).
Man(1) output converted with
man2html