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: 2
106 PMDA PMAPI Version: 2
107 pmDebug: 32768 ( libpmda )
108 Timer: off
109 Getdesc: off
110 Dump Instance Profile state=INCLUDE, 0 profiles
112 .dbpmdarc>
114 To examine the metric and instance descriptors, the desc and instance
116 commands can be used. Metrics may be identified either by name, or
117 using the ``dotted'' notation to specify the domain, cluster and item
118 fields of a PMID. Instance domains must be identified using a ``dot‐
119 ted'' notation to specify the domain and serial fields. The syntax for
120 most commands will be displayed if the command is given without any
121 arguments:
122 dbpmda> desc 253.0.0
124 PMID: 253.0.0
125 Data Type: 32-bit unsigned int InDom: PM_INDOM_NULL 0xffffffff
126 Semantics: instant Units: none
127 dbpmda> instance
128 instance indom# [ number | name | "name" ]
129 dbpmda> instance 253.0
130 pmInDom: 253.0
131 [ 0] inst: 0 name: "red"
132 [ 1] inst: 1 name: "green"
133 [ 2] inst: 2 name: "blue"
134 To test the most important component of a PMDA, the fetch, it is often
136 useful to determine the time it takes the PMDA to respond. The timer
137 may be turned on before giving a fetch:
138 dbpmda> timer on
140 dbpmda> fetch simple.numfetch 253.0.1
141 PMID(s): 253.0.0 253.0.1
142 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 2
143 253.0.0 (simple.numfetch): numval: 1 valfmt: 0 vlist[]:
144 value 1 1.4012985e-45 0x1
145 253.0.1 (simple.color): numval: 3 valfmt: 0 vlist[]:
146 inst [0 or ???] value 1 1 1.4012985e-45 0x1
147 inst [1 or ???] value 101 1.4153114e-43 0x65
148 inst [2 or ???] value 201 2.8166099e-43 0xc9
149 Timer: 0.003921 seconds
150 dbpmda> timer off
151 The integer, floating point and hex translations of the values in the
153 pmResult structure are dumped if getdesc is set to off (the default).
154 Setting getdesc to on would result in only integer values being dumped
155 in the above fetch as the descriptor describes the metrics of 32-bit
156 unsigned integers.
157 The simple PMDA also supports the store operation which can be tested
159 with subsequent fetch commands:
160 dbpmda> store simple.numfetch "42"
162 PMID: 253.0.0
163 Getting description...
164 Getting Result Structure...
165 253.0.0: 2 -> 42
166 dbpmda> fetch simple.numfetch
167 PMID(s): 253.0.0
168 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
169 253.0.0 (simple.numfetch): numval: 1 valfmt: 0 vlist[]:
170 value 43
171 The value argument in the store command must be a string, which is
173 enclosed in either single quotes (') or double quotes (").
174 A profile can be specified for each instance domain which includes all,
176 some or no instances:
177 dbpmda> help profile
179 profile indom# [ all | none ]
181 profile indom# [ add | delete ] number
182 For the instance domain specified, the profile may be changed to
184 include 'all' instances, no instances, add an instance or delete
185 an instance.
186 dbpmda> profile 253.0 none
188 dbpmda> getdesc on
189 dbpmda> fetch 253.0.1
190 PMID(s): 253.0.1
191 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
192 253.0.1 (simple.color): No values returned!
193 dbpmda> profile 253.0 add 2
194 dbpmda> fetch 253.0.1
195 PMID(s): 253.0.1
196 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
197 253.0.1 (simple.color): numval: 1 valfmt: 0 vlist[]:
198 value 202
199 dbpmda> profile 253.0 add 0
200 dbpmda> fetch 253.0.1
201 PMID(s): 253.0.1
202 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
203 253.0.1 (simple.color): numval: 2 valfmt: 0 vlist[]:
204 inst [0 or ???] value 2
205 inst [2 or ???] value 203
206 dbpmda> status
207 PMDA = pmda_simple.so
209 Connection = dso
210 pmDebug = 32768 ( libpmda )
211 Timer = off
212 Dump Instance Profile state=INCLUDE, 1 profiles
214 Profile [0] indom=1061158913 [253.0] state=EXCLUDE 2 instances
215 Instances: [2] [0]
216 dbpmda> quit
217 The watch command (usage: watch filename ) opens an xterm window which
219 tails the specified log file. This window must be closed by the user
220 when no longer required.
221 The wait command is equivalent to sleep (1) and takes a single integer
223 argument.
224 The introduction of dynamic subtrees in the PMNS and PMDA_INTERFACE_4
226 in libpcp_pmda has led to additional commands being supported in dbpmda
227 to exercise the associated dynamic PMNS services. The examples below
228 are based on the sample PMDA.
229 $ dbpmda
231 dbpmda> open pipe /var/lib/pcp/pmdas/sample/pmdasample -d 29
232 Start pmdasample PMDA: /var/lib/pcp/pmdas/sample/pmdasample -d 29
233 dbpmda> children sample.secret
234 Metric: sample.secret
235 non-leaf foo
236 leaf bar
237 dbpmda> traverse sample.secret.foo
238 Metric: sample.secret.foo
239 sample.secret.foo.bar.max.redirect
240 sample.secret.foo.one
241 sample.secret.foo.two
242 sample.secret.foo.bar.three
243 sample.secret.foo.bar.four
244 sample.secret.foo.bar.grunt.five
245 sample.secret.foo.bar.grunt.snort.six
246 sample.secret.foo.bar.grunt.snort.huff.puff.seven
247 dbpmda> pmid sample.secret.foo.bar.four
248 Metric: sample.secret.foo.bar.four
249 29.0.1004
250 dbpmda> name 29.0.1006
251 PMID: 29.0.1006
252 sample.secret.foo.bar.grunt.snort.six
253 The children command returns the next name component for all the direct
255 descendants of a node within a dynamic subtree of the PMNS. The
256 related traverse command returns the full metric names for all leaf
257 nodes in the PMNS below the specified non-leaf node in a dynamic sub‐
258 tree of the PMNS.
259 The name and pmid commands exercise the translation of metric names to
261 PMIDs (and vice versa) for metrics within a dynamic subtree of the
262 PMNS.
263 If the commands children, traverse, pmid or name are used with a PMDA
265 that is not using PMDA_INTERFACE_4 or with performance metric names
266 that are not part of a dynamic subtree of the PMNS, then the PMDA would
267 be expected to return errors (PM_ERR_NAME or PM_ERR_PMID) to reflect
268 the fact that the operation is in error (outside a dynamic subtree of
269 the PMNS it is pmcd(1) and not the PMDA that is responsible for imple‐
270 menting these functions).
271 Client authentication mechanisms have been incorporated into the PMCS,
273 providing per-user (and per-connection) information that is available
274 to PMDAs. A PMDA using PMDA_INTERFACE_6 or later in libpcp_pmda is
275 able to make use of the "attribute" method to gain visibility into
276 these authenticated connections, with access to information including
277 user and group identifiers, user name, and so on. The need to exercise
278 and debug this interface has led to a new dbpmda command. The follow‐
279 ing example is based on the sample PMDA.
280 $ dbpmda
282 dbpmda> open pipe pmdasample -D AUTH -l logfile
283 Start pmdasample PMDA: pmdasample -D AUTH -l logfile
284 dbpmda> attr "username" "tanya"
285 Attribute: username=tanya
286 Success
287 dbpmda> attr 11 "0"
288 Attribute: userid=0
289 Success
290 dbpmda>
291 The attr command passes connection attributes (PCP_ATTR keys) and their
293 values into a PMDA in much the same way that PMCD would for a client
294 connection. dbpmda always passes a client context identifier of zero,
295 and while no validity checking on values is performed only recognised
296 attributes can be set.
297 In the example above the AUTH debugging option is set for the PMDA,
299 which uses this in its attribute callback and records each attribute
300 and value pair sent to it in its logfile.
301 Note that authentication checks have already been performed by PMCD by
303 the time a PMDA is presented with these attributes, so no further veri‐
304 fication is necessary by the PMDA.
305
307 A value cannot be stored into metrics of type PM_TYPE_AGGREGATE or
308 PM_TYPE_EVENT.
309 dbpmda uses fork(2) and exec(2) to attach to daemon PMDAs. dbpmda
311 makes no attempt to detect the termination of the daemon PMDA process,
312 so it is possible for a PMDA to exit unexpectedly without any notifica‐
313 tion. However, any further communication attempts with the PMDA will
314 result in errors which will indicate that the PMDA is no longer
315 responding.
316
318 ./.dbpmdarc
319 List of commands to do on startup.
320
322 Environment variables with the prefix PCP_ are used to parameterize the
323 file and directory names used by PCP. On each installation, the file
324 /etc/pcp.conf contains the local values for these variables. The
325 $PCP_CONF variable may be used to specify an alternative configuration
326 file, as described in pcp.conf(5).
327 For environment variables affecting PCP tools, see pmGetOptions(3).
329
331 gdb(1), pmcd(1), pmdbg(1), exec(2), fork(2), PMAPI(3), PMDA(3),
332 pcp.conf(5), pcp.env(5) and PMNS(5).
333Performance Co-Pilot PCP DBPMDA(1)