1DBPMDA(1) General Commands Manual DBPMDA(1)
2
6 dbpmda - debugger for Performance Co-Pilot PMDAs
7
9 dbpmda [-efi?] [-n pmnsfile] [-q timeout] [-U username]
10
12 dbpmda is an interactive interface to the interactions between a Per‐
13 formance Metric Domain Agent (PMDA(3)) and the Performance Metric Col‐
14 lector Daemon (pmcd(1)). This allows PMDAs to be attached, initialized
15 and exercised to test for correctness.
16 dbpmda interactively prompts the user for commands, many of which emu‐
18 late the Protocol Data Units (PDUs) that may be sent by a pmcd(1)
19 process. After running dbpmda, enter the command help to get a list of
20 the available commands. The example section below illustrates a ses‐
21 sion using dbpmda to test a PMDA.
22 To simplify repetitive testing of a PMDA, the file .dbpmdarc in the
24 current working directory can contain a list of commands that will be
25 executed by dbpmda on startup, before the user is prompted to enter
26 further commands interactively. While processing the .dbpmdarc file,
27 interactive mode and command echoing are enabled and then reset at the
28 end of the .dbpmdarc file (see the -i and -e command line options
29 below).
30 The -f command line option prevents startup processing of a .dbpmdarc
32 file (if it exists).
33 If the system supports readline(3) then this will be used to read com‐
35 mands when input is from a tty device, so history and command line
36 editing are available.
37 As there are no timeout constraints on a PMDA while using dbpmda (as
39 compared to pmcd(1)), another debugger like gdb(1) can be used on the
40 PMDA process once it has been attached to dbpmda.
41
43 The available command line options are:
44 -e, --echo-input
46 Echo the input to stdout. This is useful when the input is redi‐
47 rected from a file.
48 -f, --norc
50 Do not process the .dbpmdarc file.
51 -i, --interactive
53 Emulate interactive behavior and prompt for new commands, even if
54 standard input is not a tty device.
55 -n pmnsfile, --namespace=pmnsfile
57 Load an alternative Performance Metrics Name Space (PMNS(5)) from
58 the file pmnsfile.
59 -q timeout, --creds-timeout=timeout
61 The pmcd to agent version exchange protocol (new in PCP 2.0 -
62 introduced to provide backward compatibility) uses this timeout to
63 specify how long dbpmda should wait before assuming that no ver‐
64 sion response is coming from an agent. If this timeout is
65 reached, the agent is assumed to be an agent which does not under‐
66 stand the PCP 2.0 protocol. The default timeout interval is three
67 seconds, but the -q option allows an alternative timeout interval
68 (which must be greater than zero) to be specified. The unit of
69 time is seconds.
70 -U username, --username=username
72 User account under which to run dbpmda.
73 -?, --help
75 Display usage message and exit.
76
78 Below is a dbpmda session using the simple PMDA. A .dbpmdarc file is
79 used to set the debugging option, open the PMDA and display the current
80 status of the debugger:
81 $ cat .dbpmdarc
83 debug libpmda
84 open dso pmda_simple.so simple_init 253
85 status
86 When dbpmda is run, the commands in the .dbpmdarc file are executed
88 first:
89 $ dbpmda
91 .dbpmdarc> debug libpmda
92 .dbpmdarc> open dso pmda_simple.so simple_init 253
93 [Fri Sep 19 10:19:55] dbpmda(11651) Debug: pmdaInit: PMDA simple DSO: Metric 0.0.1(1) matched to indom 253.0(0)
94 [Fri Sep 19 10:19:55] dbpmda(11651) Debug: pmdaInit: PMDA simple DSO: help file $PCP_PMDAS_DIR/simple/help opened
95 [Fri Sep 19 10:19:55] dbpmda(11651) Info: name = simple DSO
96 [Fri Sep 19 10:19:55] dbpmda(11651) Info: domain = 253
97 [Fri Sep 19 10:19:55] dbpmda(11651) Info: num metrics = 4
98 [Fri Sep 19 10:19:55] dbpmda(11651) Info: num indom = 1
99 [Fri Sep 19 10:19:55] dbpmda(11651) Info: direct map = 1
100 .dbpmdarc> status
101 Namespace: (default)
103 PMDA: ./pmda_simple.so
104 Connection: dso
105 DSO Interface Version: 7
106 PMDA PMAPI Version: 2
107 Debug options: libpmda
108 Timer: off
109 Getdesc: off
110 Getiname: off
111 Dump Instance Profile state=INCLUDE, 0 profiles
113 .dbpmdarc>
115 To examine the metric and instance domain metadata, the desc and
117 instance commands can be used. Metrics may be identified either by
118 name, or using the numeric ``dotted'' notation to specify the domain,
119 cluster and item fields of a PMID. Instance domains must be identified
120 using a numeric ``dotted'' notation to specify the domain and serial
121 fields. The syntax for most commands will be displayed if the command
122 is given without any arguments:
123 dbpmda> desc 253.0.0
125 PMID: 253.0.0
126 Data Type: 32-bit unsigned int InDom: PM_INDOM_NULL 0xffffffff
127 Semantics: instant Units: none
128 dbpmda> instance
129 instance indom# [ number | name | "name" ]
130 dbpmda> instance 253.0
131 pmInDom: 253.0
132 [ 0] inst: 0 name: "red"
133 [ 1] inst: 1 name: "green"
134 [ 2] inst: 2 name: "blue"
135 To test the most important component of a PMDA, the fetch, it is often
137 useful to determine the time it takes the PMDA to respond. The timer
138 may be turned on before giving a fetch:
139 dbpmda> timer on
141 dbpmda> fetch simple.numfetch 253.0.1
142 PMID(s): 253.0.0 253.0.1
143 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 2
144 253.0.0 (simple.numfetch): numval: 1 valfmt: 0 vlist[]:
145 value 1 1.4012985e-45 0x1
146 253.0.1 (simple.color): numval: 3 valfmt: 0 vlist[]:
147 inst [0 or ???] value 1 1 1.4012985e-45 0x1
148 inst [1 or ???] value 101 1.4153114e-43 0x65
149 inst [2 or ???] value 201 2.8166099e-43 0xc9
150 Timer: 0.003921 seconds
151 dbpmda> timer off
152 The integer, floating point and hex translations of the values in the
154 pmResult structure are dumped if getdesc is set to off (the default).
155 Setting getdesc to on also fetches the metric metadata (or pmDesc) and
156 this would result in only integer values being dumped in the above
157 fetch as the metric metadata describes the metric type to be 32-bit
158 unsigned integers.
159 Similarly, the getiname setting controls the lookup of external
161 instance names for metrics with an associated instance domain. When
162 off (the default) the output is as above. When on the instance
163 ``names'' ??? are translated into their external instance names by the
164 PMDA and reported as below:
165 dbpmda> getiname on
167 dbpmda> fetch simple.color
168 PMID(s): 253.0.1
169 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
170 253.0.1 (simple.color): numval: 3 valfmt: 0 vlist[]:
171 inst [0 or "red"] value 4
172 inst [1 or "green"] value 104
173 inst [2 or "blue"] value 204
174 Because the metric metadata is required to do the instance name lookup,
176 setting getiname to on implicitly sets getdesc to on.
177 Note that if either getdesc or getiname are set on then each fetch
179 involves additional calls on the PMDA. For a PMDA under development
180 this may not be a good idea, which is why both settings default to off.
181 The simple PMDA also supports the store operation which can be tested
183 with subsequent fetch commands:
184 dbpmda> store simple.numfetch "42"
186 PMID: 253.0.0
187 Getting description...
188 Getting Result Structure...
189 253.0.0: 2 -> 42
190 dbpmda> fetch simple.numfetch
191 PMID(s): 253.0.0
192 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
193 253.0.0 (simple.numfetch): numval: 1 valfmt: 0 vlist[]:
194 value 43
195 The value argument in the store command must be a string, which is
197 enclosed in either single quotes (') or double quotes (").
198 A profile can be specified for each instance domain which includes all,
200 some or no instances:
201 dbpmda> help profile
203 profile indom# [ all | none ]
205 profile indom# [ add | delete ] number
206 For the instance domain specified, the profile may be changed to
208 include 'all' instances, no instances, add an instance or delete
209 an instance.
210 dbpmda> profile 253.0 none
212 dbpmda> getdesc on
213 dbpmda> fetch 253.0.1
214 PMID(s): 253.0.1
215 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
216 253.0.1 (simple.color): No values returned!
217 dbpmda> profile 253.0 add 2
218 dbpmda> fetch 253.0.1
219 PMID(s): 253.0.1
220 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
221 253.0.1 (simple.color): numval: 1 valfmt: 0 vlist[]:
222 value 202
223 dbpmda> profile 253.0 add 0
224 dbpmda> fetch 253.0.1
225 PMID(s): 253.0.1
226 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
227 253.0.1 (simple.color): numval: 2 valfmt: 0 vlist[]:
228 inst [0 or ???] value 2
229 inst [2 or ???] value 203
230 dbpmda> status
231 Namespace: (default)
233 PMDA: ./pmda_simple.so
234 Connection: dso
235 DSO Interface Version: 7
236 PMDA PMAPI Version: 2
237 Debug options: (none)
238 Timer: off
239 Getdesc: off
240 Getiname: off
241 Dump Instance Profile state=INCLUDE, 1 profiles
243 Profile [0] indom=1061158913 [253.0] state=EXCLUDE 2 instances
244 Instances: [2] [0]
245 dbpmda> quit
246 The watch command (usage: watch filename ) opens an xterm window which
248 tails the specified log file. This window must be closed by the user
249 when no longer required.
250 The wait command is equivalent to sleep(1) and takes a single integer
252 argument (wait time in seconds).
253 The introduction of dynamic subtrees in the PMNS and PMDA_INTERFACE_4
255 in libpcp_pmda has led to additional commands being supported in dbpmda
256 to exercise the associated dynamic PMNS services. The examples below
257 are based on the sample PMDA.
258 $ dbpmda
260 dbpmda> open pipe /var/lib/pcp/pmdas/sample/pmdasample -d 29
261 Start pmdasample PMDA: /var/lib/pcp/pmdas/sample/pmdasample -d 29
262 dbpmda> children sample.secret
263 Metric: sample.secret
264 non-leaf foo
265 leaf bar
266 dbpmda> traverse sample.secret.foo
267 Metric: sample.secret.foo
268 sample.secret.foo.bar.max.redirect
269 sample.secret.foo.one
270 sample.secret.foo.two
271 sample.secret.foo.bar.three
272 sample.secret.foo.bar.four
273 sample.secret.foo.bar.grunt.five
274 sample.secret.foo.bar.grunt.snort.six
275 sample.secret.foo.bar.grunt.snort.huff.puff.seven
276 dbpmda> pmid sample.secret.foo.bar.four
277 Metric: sample.secret.foo.bar.four
278 29.0.1004
279 dbpmda> name 29.0.1006
280 PMID: 29.0.1006
281 sample.secret.foo.bar.grunt.snort.six
282 The children command returns the next name component for all the direct
284 descendants of a node within a dynamic subtree of the PMNS. The
285 related traverse command returns the full metric names for all leaf
286 nodes in the PMNS below the specified non-leaf node in a dynamic sub‐
287 tree of the PMNS.
288 The name and pmid commands exercise the translation of metric names to
290 PMIDs (and vice versa) for metrics within a dynamic subtree of the
291 PMNS.
292 If the commands children, traverse, pmid or name are used with a PMDA
294 that is not using PMDA_INTERFACE_4 or with performance metric names
295 that are not part of a dynamic subtree of the PMNS, then the PMDA would
296 be expected to return errors (PM_ERR_NAME or PM_ERR_PMID) to reflect
297 the fact that the operation is in error (outside a dynamic subtree of
298 the PMNS it is pmcd(1) and not the PMDA that is responsible for imple‐
299 menting these functions).
300 Client authentication mechanisms have been incorporated into the PMCS,
302 providing per-user (and per-connection) information that is available
303 to PMDAs. A PMDA using PMDA_INTERFACE_6 or later in libpcp_pmda is
304 able to make use of the "attribute" method to gain visibility into
305 these authenticated connections, with access to information including
306 user and group identifiers, user name, and so on. The need to exercise
307 and debug this interface has led to a new dbpmda command. The follow‐
308 ing example is based on the sample PMDA.
309 $ dbpmda
311 dbpmda> open pipe pmdasample -D AUTH -l logfile
312 Start pmdasample PMDA: pmdasample -D AUTH -l logfile
313 dbpmda> attr "username" "tanya"
314 Attribute: username=tanya
315 Success
316 dbpmda> attr 11 "0"
317 Attribute: userid=0
318 Success
319 dbpmda>
320 The attr command passes connection attributes (PCP_ATTR keys) and their
322 values into a PMDA in much the same way that PMCD would for a client
323 connection. dbpmda always passes a client context identifier of zero,
324 and while no validity checking on values is performed only recognised
325 attributes can be set.
326 In the example above the AUTH debugging option is set for the PMDA,
328 which uses this in its attribute callback and records each attribute
329 and value pair sent to it in its logfile.
330 Note that authentication checks have already been performed by PMCD by
332 the time a PMDA is presented with these attributes, so no further veri‐
333 fication is necessary by the PMDA.
334 The debug command takes one or more debug options separated by white‐
336 space or a comma. This can be used to selectively enable or disable
337 debugging output from various modules of the PCP libraries that the
338 PMDA will be linked with. The options are the same debug names as
339 reported by the -l option to pmdbg(1) and/or their deprecated equiva‐
340 lent numeric values as reported by the -ol options to pmdbg(1). The
341 special ``option'' none turns all debugging off and the special
342 ``option'' all enables all the debugging options.
343
345 A value cannot be stored into metrics of type PM_TYPE_AGGREGATE or
346 PM_TYPE_EVENT.
347 dbpmda uses fork(2) and exec(2) to attach to daemon PMDAs. dbpmda
349 makes no attempt to detect the termination of the daemon PMDA process,
350 so it is possible for a PMDA to exit unexpectedly without any notifica‐
351 tion. However, any further communication attempts with the PMDA will
352 result in errors which will indicate that the PMDA is no longer
353 responding.
354
356 ./.dbpmdarc
357 List of commands to do on startup.
358
360 Environment variables with the prefix PCP_ are used to parameterize the
361 file and directory names used by PCP. On each installation, the file
362 /etc/pcp.conf contains the local values for these variables. The
363 $PCP_CONF variable may be used to specify an alternative configuration
364 file, as described in pcp.conf(5).
365 For environment variables affecting PCP tools, see pmGetOptions(3).
367
369 gdb(1), pmcd(1), pmdbg(1), exec(2), fork(2), PMAPI(3), PMDA(3),
370 pcp.conf(5), pcp.env(5) and PMNS(5).
371Performance Co-Pilot PCP DBPMDA(1)