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

NAME

6       pmdapipe  -  command  output  capture  performance metrics domain agent
7       (PMDA)
8

SYNOPSIS

10       $PCP_PMDAS_DIR/pipe/pmdapipe [-c configfile] [-d domain]  [-l  logfile]
11       [-m memory]
12

DESCRIPTION

14       pmdapipe  is  a configurable command output monitoring Performance Met‐
15       rics Domain Agent (PMDA).  It can be seen as analogous to a  restricted
16       shell, where options can be passed to preset commands, and each line of
17       their output is converted into a performance event.  These  events  can
18       be consumed by client tools like pmval(1).
19
20       The  pipe  PMDA exports both event-style metrics reflecting timestamped
21       event records for text-oriented command output, as well as the more or‐
22       thodox  sample-style  metrics  such as event counts and throughput size
23       values.
24
25       The PMDA is configured via a configfile which  contains  one  line  for
26       each  process  from  which  output can be captured, as described in the
27       ``CONFIGURATION'' section below.
28
29       A brief description of the pmdapipe command line options follows:
30
31       -c   specifies an alternate configuration file for the  PMDA.   By  de‐
32            fault,  a  file  named $PCP_PMDAS_DIR/pipe/pipe.conf and any files
33            below the $PCP_SYSCONF_DIR/pipe.conf.d/ directory are used.
34
35       -d   It is absolutely crucial that the performance metrics domain  num‐
36            ber  specified  here  is  unique  and consistent.  That is, domain
37            should be different for every PMDA on the one host, and  the  same
38            domain number should be used for the same PMDA on all hosts.
39
40       -l   Location  of  the log file.  By default, a log file named pipe.log
41            is written in the current directory of pmcd(1)  when  pmdapipe  is
42            started,  i.e.  $PCP_LOG_DIR/pmcd.  If the log file cannot be cre‐
43            ated or is not writable, output is written to the  standard  error
44            instead.
45
46       -m   Limit the physical memory used by the PMDA to buffer event records
47            to maxsize bytes.  As log events arrive at the PMDA, they must  be
48            buffered  until  individual  client  tools  request the next batch
49            since their previous batch of events.  The default  maximum  is  2
50            megabytes.
51

CONFIGURATION

53       The  set of allowed pipe commands is configured by simple text file(s).
54       The format is a single line for each command followed  by  an  optional
55       access control section.
56
57       Blank lines and comments are permitted (even encouraged) in the config‐
58       uration file.  A comment begins with a ``#'' character and finishes  at
59       the end of the line.
60
61       Each command configuration line is of the form:
62
63              instance username command options
64
65       Where,
66
67       instance      is  a  string identifying the pipe command, also exported
68                     as the metric instance identifier.
69       username      is the name of the user account under which  the  command
70                     should run (e.g. "root")
71       command       is  the  path to the binary which will be run to generate
72                     piped output
73       options       is an optional space-separated list of parameters to pass
74                     to the command
75
76                     This options list may contain numeric parameters prefixed
77                     by the dollar-sign, and these will  be  substituted  with
78                     user-supplied values at the time the command is run (sim‐
79                     ilar to shell parameter substitution).
80
81       Parameters are passed as a single  space-separated  or  comma-separated
82       string  to  the  pipe.firehose metric, using the pmStore (3) interface.
83       The pmval command provides store access via its -x  option.   User-sup‐
84       plied parameters are restricted to containing alphanumeric characters.
85
86       The  access  control  section of the file must start with a line of the
87       form:
88
89       [access]
90
91       Leading and trailing whitespace may appear around and within the brack‐
92       ets  and  the case of the access keyword is ignored.  No other text may
93       appear on the line except a trailing comment.
94
95       Following this line, the remainder of  the  configuration  file  should
96       contain  lines  that  allow or disallow use of commands from particular
97       users or groups.
98
99       User names and group names will be verified using the local /etc/passwd
100       and  /etc/groups files (or an alternative directory service), using the
101       getpwent(3) and getgrent(3) routines.
102
103       Access for users or groups are  allowed  or  disallowed  by  specifying
104       statements of the form:
105
106              allow user username : instance
107              disallow user username : instance
108              allow group groupname : instance
109              disallow group groupname : instance
110
111       The  username  and  groupname  names  will  be verified using the local
112       /etc/passwd and /etc/groups files (or  an  alternative  directory  ser‐
113       vice), using the getpwent(3) and getgrent(3) routines.
114
115       The wildcard ``*'' can be used to refer to all instance names.
116

INSTALLATION

118       If you want access to the names, help text and values for the pipe per‐
119       formance metrics, do the following as root:
120
121            # cd $PCP_PMDAS_DIR/pipe
122            # ./Install
123
124       This is an interactive installation process which prompts for each  log
125       file  path  to  be  monitored (or command to be run), a metric instance
126       name to identify it, and whether access should be restricted (refer  to
127       the -x option to pmval(1) for further details).
128
129       If you want to undo the installation, do the following as root:
130
131            # cd $PCP_PMDAS_DIR/pipe
132            # ./Remove
133
134       pmdapipe  is  launched  by  pmcd and should never be executed directly.
135       The Install and Remove scripts notify pmcd when the agent is  installed
136       or removed.
137

EXAMPLES

139       Following  is a simple example of pmdapipe configuration and use of the
140       pipe metrics to run the btrace command, by user bob:
141
142            bob> cat $PCP_PMDAS_DIR/pipe/pipe.conf
143            # instance      user      command
144            rw_syscalls     root      perf script rw-by-file $1
145            bdev_trace      root      btrace -w $1 /dev/$2
146
147            [access]
148            allow user bob : *;
149            allow user jane : bdev_trace;
150            allow group perf : rw_syscalls;
151
152            bob> pmval -i bdev_trace -x '5 sda' pipe.firehose
153             8,2  5  1  0.000000000 25227  A  WS 734332384 + 24 <- (253,2) 734330336
154             8,0  5  2  0.000000414 25227  A  WS 735358432 + 24 <- (8,2) 734332384
155             8,0  5  3  0.000000756 25227  Q  WS 735358432 + 24 [qemu-kvm]
156             [...5 seconds worth]
157            bob>
158

FILES

160       $PCP_PMCDCONF_PATH
161                 command line options used to launch pmdapipe
162       $PCP_PMDAS_DIR/pipe/pipe.conf
163                 default configuration file for the pipe metrics
164       $PCP_PMDAS_DIR/pipe/help
165                 default help text file for the pipe metrics
166       $PCP_PMDAS_DIR/pipe/Install
167                 installation script for the pmdapipe agent
168       $PCP_PMDAS_DIR/pipe/Remove
169                 undo installation script for the pmdapipe agent
170       $PCP_LOG_DIR/pmcd/pipe.log
171                 default log file for error  messages  and  other  information
172                 from pmdapipe
173       $PCP_SYSCONF_DIR/pipe.conf.d
174                 directory  containing  additional configuration files for the
175                 pipe metrics
176

PCP ENVIRONMENT

178       Environment variables with the prefix PCP_ are used to parameterize the
179       file  and  directory names used by PCP.  On each installation, the file
180       /etc/pcp.conf contains the  local  values  for  these  variables.   The
181       $PCP_CONF  variable may be used to specify an alternative configuration
182       file, as described in pcp.conf(5).
183

SEE ALSO

185       PCPIntro(1), pmval(1), pmcd(1), getpwent(3),  getgrent(3),  pmStore(3),
186       pcp.conf(5) and pcp.env(5).
187
188
189
190Performance Co-Pilot                  PCP                          PMDAPIPE(1)
Impressum