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