1PMDASHPING(1)               General Commands Manual              PMDASHPING(1)
2
3
4

NAME

6       pmdashping - "shell-ping" performance metrics domain agent
7

SYNOPSIS

9       $PCP_PMDAS_DIR/shping/pmdashping  [-C] [-d domain] [-l logfile] [-I in‐
10       terval] [-t timeout] [-U username] configfile
11

DESCRIPTION

13       pmdashping is a Performance Metrics Domain Agent (PMDA)  which  exports
14       quality  of  service  and response time measurements for arbitrary com‐
15       mands as might be run from a shell such as sh(1).
16
17       These measurements are intended to be used to quantify service  quality
18       and  service  availability  for  those services that are either mission
19       critical or act as early indicators of adverse system performance.
20
21       The sample configuration  monitors  simple  shell  commands  (exit  and
22       date(1)),  a short computationally intensive task using sum(1), a short
23       C compilation, DNS lookup via  nslookup(1),  YP  lookup  via  ypcat(1),
24       bind/portmapper  service using rpcbind(1), SMTP by connecting to telnet
25       port 25 and sending an ``expn root'' request, and NNTP by connecting to
26       telnet port 119 and running a ``listgroup'' command.
27
28       It  is  expected  that  other commands would follow the examples in the
29       sample configuration file, and most deployments of the pmdashping  PMDA
30       are expected to use a customized configuration file.
31
32       A brief description of the pmdashping command line options follows:
33
34       -C   Parse  configfile,  reporting any errors and exiting with non-zero
35            status if the file contains syntactical errors.
36
37       -d   It is absolutely crucial that the performance metrics domain  num‐
38            ber  specified  here  is  unique  and consistent.  That is, domain
39            should be different for every PMDA on the one host, and  the  same
40            domain number should be used for the same PMDA on all hosts.
41
42       -l   Location of the log file.  By default, a log file named shping.log
43            is written in the current directory of pmcd(1) when pmdashping  is
44            started,  i.e.  $PCP_LOG_DIR/pmcd.  If the log file cannot be cre‐
45            ated or is not writable, output is written to the  standard  error
46            instead.
47
48       -I   Amount  of  time (in seconds) between subsequent executions of the
49            list of commands provided via the configuration  file  configfile.
50            The default is 2 minutes.
51
52       -t   Amount  of  time (in seconds) to wait before timing out awaiting a
53            response for a command from configfile.  The default  is  20  sec‐
54            onds.
55
56       -U   User  account  under which to run the agent and all commands.  The
57            default is the unprivileged "pcp" account in current  versions  of
58            PCP, but in older versions the superuser account ("root") was used
59            by default.
60
61       The required configfile specifies ``tag'' and ``command''  pairs,  each
62       on  a  separate  line.   All of the commands are run one after another,
63       with the whole group rescheduled to be run once per interval.  For each
64       command that is run, pmdashping records information related to the suc‐
65       cess (or timeout), exit status, elapsed time and CPU time  (system  and
66       user), and this information is exported by the PMDA.  The tags are used
67       to identify the individual commands amongst the values exported by  the
68       PMDA, and form the external instance domain identifiers for the pmdash‐
69       ping metrics which relate to each command.
70

INSTALLATION

72       In order for a host to export the names, help text and values  for  the
73       shping performance metrics, do the following as root:
74
75            # cd $PCP_PMDAS_DIR/shping
76            # ./Install
77
78       The  set  of  ``tag'' and ``command'' pairs may be specified from a de‐
79       fault (sample) configuration file, a customized file or entered  inter‐
80       actively as part of the Install script.
81
82       If you want to undo the installation, do the following as root:
83
84            # cd $PCP_PMDAS_DIR/shping
85            # ./Remove
86
87       pmdashping  is  launched  by  pmcd(1)  and should never be executed di‐
88       rectly.  The Install and Remove scripts notify pmcd(1) when  the  agent
89       is installed or removed.
90

FILES

92       $PCP_PMCDCONF_PATH
93                 command line options used to launch pmdashping
94       $PCP_PMDAS_DIR/shping/help
95                 default help text file for the shping metrics
96       $PCP_PMDAS_DIR/shping/sample.conf
97                 example configuration file with a number of common commands
98       $PCP_PMDAS_DIR/shping/Install
99                 installation script for the pmdashping agent
100       $PCP_PMDAS_DIR/shping/Remove
101                 undo installation script for pmdashping
102       $PCP_LOG_DIR/pmcd/shping.log
103                 default  log  file  for  error messages and other information
104                 from pmdashping
105

PCP ENVIRONMENT

107       Environment variables with the prefix PCP_ are used to parameterize the
108       file  and  directory names used by PCP.  On each installation, the file
109       /etc/pcp.conf contains the  local  values  for  these  variables.   The
110       $PCP_CONF  variable may be used to specify an alternative configuration
111       file, as described in pcp.conf(5).
112

SEE ALSO

114       PCPIntro(1), pmcd(1) and pcp-shping(1).
115
116
117
118Performance Co-Pilot                  PCP                        PMDASHPING(1)
Impressum