1PMDAPIPE(1) General Commands Manual PMDAPIPE(1)
2
6 pmdapipe - command output capture performance metrics domain agent
7 (PMDA)
8
10 $PCP_PMDAS_DIR/pipe/pmdapipe [-c configfile] [-d domain] [-l logfile]
11 [-m memory]
12
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 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 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 A brief description of the pmdapipe command line options follows:
30 -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 -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 -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 -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
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 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 Each command configuration line is of the form:
62 instance username command options
64 Where,
66 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 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 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 The access control section of the file must start with a line of the
87 form:
88 [access]
90 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 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 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 Access for users or groups are allowed or disallowed by specifying
104 statements of the form:
105 allow user username : instance
107 disallow user username : instance
108 allow group groupname : instance
109 disallow group groupname : instance
110 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 The wildcard ``*'' can be used to refer to all instance names.
116
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 # cd $PCP_PMDAS_DIR/pipe
122 # ./Install
123 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 If you want to undo the installation, do the following as root:
130 # cd $PCP_PMDAS_DIR/pipe
132 # ./Remove
133 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
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 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 [access]
148 allow user bob : *;
149 allow user jane : bdev_trace;
150 allow group perf : rw_syscalls;
151 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
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
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
185 PCPIntro(1), pmval(1), pmcd(1), getpwent(3), getgrent(3), pmStore(3),
186 pcp.conf(5) and pcp.env(5).
187Performance Co-Pilot PCP PMDAPIPE(1)