1DBPMDA(1) General Commands Manual DBPMDA(1)
2
6 dbpmda - debugger for Performance Co-Pilot PMDAs
7
9 dbpmda [-efiv?] [-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 be‐
29 low).
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 - in‐
62 troduced 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 -v, --valgrind
75 Useful when running dbpmda under the control of valgrind(1) to
76 triage problems in a DSO PMDA. If the -v option is used then dbp‐
77 mda will do not call dlclose(3) before exiting, this allows val‐
78 grind(1) to access the symbol table of the DSO PMDA when reporting
79 which makes debugging much easier.
80 -?, --help
82 Display usage message and exit.
83
85 Below is a dbpmda session using the simple PMDA. A .dbpmdarc file is
86 used to set the debugging option, open the PMDA and display the current
87 status of the debugger:
88 $ cat .dbpmdarc
90 debug libpmda
91 open dso pmda_simple.so simple_init 253
92 status
93 When dbpmda is run, the commands in the .dbpmdarc file are executed
95 first:
96 $ dbpmda
98 .dbpmdarc> debug libpmda
99 .dbpmdarc> open dso pmda_simple.so simple_init 253
100 [Fri Sep 19 10:19:55] dbpmda(11651) Debug: pmdaInit: PMDA simple DSO: Metric 0.0.1(1) matched to indom 253.0(0)
101 [Fri Sep 19 10:19:55] dbpmda(11651) Debug: pmdaInit: PMDA simple DSO: help file $PCP_PMDAS_DIR/simple/help opened
102 [Fri Sep 19 10:19:55] dbpmda(11651) Info: name = simple DSO
103 [Fri Sep 19 10:19:55] dbpmda(11651) Info: domain = 253
104 [Fri Sep 19 10:19:55] dbpmda(11651) Info: num metrics = 4
105 [Fri Sep 19 10:19:55] dbpmda(11651) Info: num indom = 1
106 [Fri Sep 19 10:19:55] dbpmda(11651) Info: direct map = 1
107 .dbpmdarc> status
108 Namespace: (default)
110 PMDA: ./pmda_simple.so
111 Connection: dso
112 DSO Interface Version: 7
113 PMDA PMAPI Version: 2
114 Debug options: libpmda
115 Timer: off
116 Getdesc: off
117 Getiname: off
118 Dump Instance Profile state=INCLUDE, 0 profiles
120 .dbpmdarc>
122 To examine the metric and instance domain metadata, the desc and in‐
124 stance commands can be used. Metrics may be identified either by name,
125 or using the numeric ``dotted'' notation to specify the domain, cluster
126 and item fields of a PMID. Instance domains must be identified using a
127 numeric ``dotted'' notation to specify the domain and serial fields.
128 The syntax for most commands will be displayed if the command is given
129 without any arguments:
130 dbpmda> desc 253.0.0
132 PMID: 253.0.0
133 Data Type: 32-bit unsigned int InDom: PM_INDOM_NULL 0xffffffff
134 Semantics: instant Units: none
135 dbpmda> instance
136 instance indom# [ number | name | "name" ]
137 dbpmda> instance 253.0
138 pmInDom: 253.0
139 [ 0] inst: 0 name: "red"
140 [ 1] inst: 1 name: "green"
141 [ 2] inst: 2 name: "blue"
142 To test the most important component of a PMDA, the fetch, it is often
144 useful to determine the time it takes the PMDA to respond. The timer
145 may be turned on before giving a fetch:
146 dbpmda> timer on
148 dbpmda> fetch simple.numfetch 253.0.1
149 PMID(s): 253.0.0 253.0.1
150 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 2
151 253.0.0 (simple.numfetch): numval: 1 valfmt: 0 vlist[]:
152 value 1 1.4012985e-45 0x1
153 253.0.1 (simple.color): numval: 3 valfmt: 0 vlist[]:
154 inst [0 or ???] value 1 1 1.4012985e-45 0x1
155 inst [1 or ???] value 101 1.4153114e-43 0x65
156 inst [2 or ???] value 201 2.8166099e-43 0xc9
157 Timer: 0.003921 seconds
158 dbpmda> timer off
159 The integer, floating point and hex translations of the values in the
161 pmResult structure are dumped if getdesc is set to off (the default).
162 Setting getdesc to on also fetches the metric metadata (or pmDesc) and
163 this would result in only integer values being dumped in the above
164 fetch as the metric metadata describes the metric type to be 32-bit un‐
165 signed integers.
166 Similarly, the getiname setting controls the lookup of external in‐
168 stance names for metrics with an associated instance domain. When off
169 (the default) the output is as above. When on the instance ``names''
170 ??? are translated into their external instance names by the PMDA and
171 reported as below:
172 dbpmda> getiname on
174 dbpmda> fetch simple.color
175 PMID(s): 253.0.1
176 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
177 253.0.1 (simple.color): numval: 3 valfmt: 0 vlist[]:
178 inst [0 or "red"] value 4
179 inst [1 or "green"] value 104
180 inst [2 or "blue"] value 204
181 Because the metric metadata is required to do the instance name lookup,
183 setting getiname to on implicitly sets getdesc to on.
184 Note that if either getdesc or getiname are set on then each fetch in‐
186 volves additional calls on the PMDA. For a PMDA under development this
187 may not be a good idea, which is why both settings default to off.
188 The simple PMDA also supports the store operation which can be tested
190 with subsequent fetch commands:
191 dbpmda> store simple.numfetch "42"
193 PMID: 253.0.0
194 Getting description...
195 Getting Result Structure...
196 253.0.0: 2 -> 42
197 dbpmda> fetch simple.numfetch
198 PMID(s): 253.0.0
199 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
200 253.0.0 (simple.numfetch): numval: 1 valfmt: 0 vlist[]:
201 value 43
202 The value argument in the store command must be a string, which is en‐
204 closed in either single quotes (') or double quotes (").
205 A profile can be specified for each instance domain which includes all,
207 some or no instances:
208 dbpmda> help profile
210 profile indom# [ all | none ]
212 profile indom# [ add | delete ] number
213 For the instance domain specified, the profile may be changed to
215 include 'all' instances, no instances, add an instance or delete
216 an instance.
217 dbpmda> profile 253.0 none
219 dbpmda> getdesc on
220 dbpmda> fetch 253.0.1
221 PMID(s): 253.0.1
222 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
223 253.0.1 (simple.color): No values returned!
224 dbpmda> profile 253.0 add 2
225 dbpmda> fetch 253.0.1
226 PMID(s): 253.0.1
227 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
228 253.0.1 (simple.color): numval: 1 valfmt: 0 vlist[]:
229 value 202
230 dbpmda> profile 253.0 add 0
231 dbpmda> fetch 253.0.1
232 PMID(s): 253.0.1
233 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
234 253.0.1 (simple.color): numval: 2 valfmt: 0 vlist[]:
235 inst [0 or ???] value 2
236 inst [2 or ???] value 203
237 dbpmda> status
238 Namespace: (default)
240 PMDA: ./pmda_simple.so
241 Connection: dso
242 DSO Interface Version: 7
243 PMDA PMAPI Version: 2
244 Debug options: (none)
245 Timer: off
246 Getdesc: off
247 Getiname: off
248 Dump Instance Profile state=INCLUDE, 1 profiles
250 Profile [0] indom=1061158913 [253.0] state=EXCLUDE 2 instances
251 Instances: [2] [0]
252 dbpmda> quit
253 The watch command (usage: watch filename ) opens an xterm window which
255 tails the specified log file. This window must be closed by the user
256 when no longer required.
257 The wait command is equivalent to sleep(1) and takes a single integer
259 argument (wait time in seconds).
260 The introduction of dynamic subtrees in the PMNS and PMDA_INTERFACE_4
262 in libpcp_pmda has led to additional commands being supported in dbpmda
263 to exercise the associated dynamic PMNS services. The examples below
264 are based on the sample PMDA.
265 $ dbpmda
267 dbpmda> open pipe /var/lib/pcp/pmdas/sample/pmdasample -d 29
268 Start pmdasample PMDA: /var/lib/pcp/pmdas/sample/pmdasample -d 29
269 dbpmda> children sample.secret
270 Metric: sample.secret
271 non-leaf foo
272 leaf bar
273 dbpmda> traverse sample.secret.foo
274 Metric: sample.secret.foo
275 sample.secret.foo.bar.max.redirect
276 sample.secret.foo.one
277 sample.secret.foo.two
278 sample.secret.foo.bar.three
279 sample.secret.foo.bar.four
280 sample.secret.foo.bar.grunt.five
281 sample.secret.foo.bar.grunt.snort.six
282 sample.secret.foo.bar.grunt.snort.huff.puff.seven
283 dbpmda> pmid sample.secret.foo.bar.four
284 Metric: sample.secret.foo.bar.four
285 29.0.1004
286 dbpmda> name 29.0.1006
287 PMID: 29.0.1006
288 sample.secret.foo.bar.grunt.snort.six
289 The children command returns the next name component for all the direct
291 descendants of a node within a dynamic subtree of the PMNS. The re‐
292 lated traverse command returns the full metric names for all leaf nodes
293 in the PMNS below the specified non-leaf node in a dynamic subtree of
294 the PMNS.
295 The name and pmid commands exercise the translation of metric names to
297 PMIDs (and vice versa) for metrics within a dynamic subtree of the
298 PMNS.
299 If the commands children, traverse, pmid or name are used with a PMDA
301 that is not using PMDA_INTERFACE_4 or with performance metric names
302 that are not part of a dynamic subtree of the PMNS, then the PMDA would
303 be expected to return errors (PM_ERR_NAME or PM_ERR_PMID) to reflect
304 the fact that the operation is in error (outside a dynamic subtree of
305 the PMNS it is pmcd(1) and not the PMDA that is responsible for imple‐
306 menting these functions).
307 Client authentication mechanisms have been incorporated into the PMCS,
309 providing per-user (and per-connection) information that is available
310 to PMDAs. A PMDA using PMDA_INTERFACE_6 or later in libpcp_pmda is
311 able to make use of the "attribute" method to gain visibility into
312 these authenticated connections, with access to information including
313 user and group identifiers, user name, and so on. The need to exercise
314 and debug this interface has led to a new dbpmda command. The follow‐
315 ing example is based on the sample PMDA.
316 $ dbpmda
318 dbpmda> open pipe pmdasample -D AUTH -l logfile
319 Start pmdasample PMDA: pmdasample -D AUTH -l logfile
320 dbpmda> attr "username" "tanya"
321 Attribute: username=tanya
322 Success
323 dbpmda> attr 11 "0"
324 Attribute: userid=0
325 Success
326 dbpmda>
327 The attr command passes connection attributes (PCP_ATTR keys) and their
329 values into a PMDA in much the same way that PMCD would for a client
330 connection. dbpmda always passes a client context identifier of zero,
331 and while no validity checking on values is performed only recognised
332 attributes can be set.
333 In the example above the AUTH debugging option is set for the PMDA,
335 which uses this in its attribute callback and records each attribute
336 and value pair sent to it in its logfile.
337 Note that authentication checks have already been performed by PMCD by
339 the time a PMDA is presented with these attributes, so no further veri‐
340 fication is necessary by the PMDA.
341 The debug command takes one or more debug options separated by white‐
343 space or a comma. This can be used to selectively enable debugging
344 output from various modules of the PCP libraries that the PMDA will be
345 linked with. If the option is prefixed by a minus ``-'' the corre‐
346 sponding debugging option is disabled. The options are the same debug
347 names as reported by the -l option to pmdbg(1) and/or their deprecated
348 equivalent numeric values as reported by the -ol options to pmdbg(1).
349 The special ``option'' none turns all debugging off and the special
350 ``option'' all enables all the debugging options.
351
353 A value cannot be stored into metrics of type PM_TYPE_AGGREGATE or
354 PM_TYPE_EVENT.
355 dbpmda uses fork(2) and exec(2) to attach to daemon PMDAs. dbpmda
357 makes no attempt to detect the termination of the daemon PMDA process,
358 so it is possible for a PMDA to exit unexpectedly without any notifica‐
359 tion. However, any further communication attempts with the PMDA will
360 result in errors which will indicate that the PMDA is no longer re‐
361 sponding.
362
364 ./.dbpmdarc
365 List of commands to do on startup.
366
368 Environment variables with the prefix PCP_ are used to parameterize the
369 file and directory names used by PCP. On each installation, the file
370 /etc/pcp.conf contains the local values for these variables. The
371 $PCP_CONF variable may be used to specify an alternative configuration
372 file, as described in pcp.conf(5).
373 For environment variables affecting PCP tools, see pmGetOptions(3).
375
377 gdb(1), pmcd(1), pmdbg(1), exec(2), fork(2), PMAPI(3), PMDA(3),
378 pcp.conf(5), pcp.env(5) and PMNS(5).
379Performance Co-Pilot PCP DBPMDA(1)