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 arguments
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 dbpmda accepts the following command line arguments:
39 -e Echo the input to stdout. This is useful when the input is
41 redirected from a file.
42 -i Emulate interactive behavior and prompt for new commands, even
44 if standard input is not a tty device.
45 -n pmnsfile
47 Normally dbpmda operates on the distributed Performance Metrics
48 Name Space (PMNS), however if the -n option is specified an
49 alternative local PMNS is loaded from the file pmnsfile.
50 -q timeout
52 The pmcd to agent version exchange protocol (new in PCP 2.0 -
53 introduced to provide backward compatibility) uses this timeout
54 to specify how long dbpmda should wait before assuming that no
55 version response is coming from an agent. If this timeout is
56 reached, the agent is assumed to be an agent which does not
57 understand the PCP 2.0 protocol. The default timeout interval
58 is five seconds, but the -q option allows an alternative timeout
59 interval (which must be greater than zero) to be specified. The
60 unit of time is seconds.
61 -U username
63 User account under which to run dbpmda.
64 As there are no timeout constraints on a PMDA while using dbpmda (as
66 compared to pmcd(1)), another debugger like gdb(1) can be used on the
67 PMDA process once it has been attached to dbpmda.
68
70 Below is a dbpmda session using the simple PMDA. A .dbpmdarc file is
71 used to set the debugging option, open the PMDA and display the current
72 status of the debugger:
73 $ cat .dbpmdarc
75 debug libpmda
76 open dso pmda_simple.so simple_init 253
77 status
78 When dbpmda is run, the commands in the .dbpmdarc file are executed
80 first:
81 $ dbpmda
83 .dbpmdarc> debug libpmda
84 .dbpmdarc> open dso pmda_simple.so simple_init 253
85 [Fri Sep 19 10:19:55] dbpmda(11651) Debug: pmdaInit: PMDA simple DSO: Metric 0.0.1(1) matched to indom 253.0(0)
86 [Fri Sep 19 10:19:55] dbpmda(11651) Debug: pmdaInit: PMDA simple DSO: help file $PCP_PMDAS_DIR/simple/help opened
87 [Fri Sep 19 10:19:55] dbpmda(11651) Info: name = simple DSO
88 [Fri Sep 19 10:19:55] dbpmda(11651) Info: domain = 253
89 [Fri Sep 19 10:19:55] dbpmda(11651) Info: num metrics = 4
90 [Fri Sep 19 10:19:55] dbpmda(11651) Info: num indom = 1
91 [Fri Sep 19 10:19:55] dbpmda(11651) Info: direct map = 1
92 .dbpmdarc> status
93 Namespace: (default)
95 PMDA: ./pmda_simple.so
96 Connection: dso
97 DSO Interface Version: 2
98 PMDA PMAPI Version: 2
99 pmDebug: 32768 ( libpmda )
100 Timer: off
101 Getdesc: off
102 Dump Instance Profile state=INCLUDE, 0 profiles
104 .dbpmdarc>
106 To examine the metric and instance descriptors, the desc and instance
108 commands can be used. Metrics may be identified either by name, or
109 using the ``dotted'' notation to specify the domain, cluster and item
110 fields of a PMID. Instance domains must be identified using a ``dot‐
111 ted'' notation to specify the domain and serial fields. The syntax for
112 most commands will be displayed if the command is given without any
113 arguments:
114 dbpmda> desc 253.0.0
116 PMID: 253.0.0
117 Data Type: 32-bit unsigned int InDom: PM_INDOM_NULL 0xffffffff
118 Semantics: instant Units: none
119 dbpmda> instance
120 instance indom# [ number | name | "name" ]
121 dbpmda> instance 253.0
122 pmInDom: 253.0
123 [ 0] inst: 0 name: "red"
124 [ 1] inst: 1 name: "green"
125 [ 2] inst: 2 name: "blue"
126 To test the most important component of a PMDA, the fetch, it is often
128 useful to determine the time it takes the PMDA to respond. The timer
129 may be turned on before giving a fetch:
130 dbpmda> timer on
132 dbpmda> fetch simple.numfetch 253.0.1
133 PMID(s): 253.0.0 253.0.1
134 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 2
135 253.0.0 (simple.numfetch): numval: 1 valfmt: 0 vlist[]:
136 value 1 1.4012985e-45 0x1
137 253.0.1 (simple.color): numval: 3 valfmt: 0 vlist[]:
138 inst [0 or ???] value 1 1 1.4012985e-45 0x1
139 inst [1 or ???] value 101 1.4153114e-43 0x65
140 inst [2 or ???] value 201 2.8166099e-43 0xc9
141 Timer: 0.003921 seconds
142 dbpmda> timer off
143 The integer, floating point and hex translations of the values in the
145 pmResult structure are dumped if getdesc is set to off (the default).
146 Setting getdesc to on would result in only integer values being dumped
147 in the above fetch as the descriptor describes the metrics of 32-bit
148 unsigned integers.
149 The simple PMDA also supports the store operation which can be tested
151 with subsequent fetch commands:
152 dbpmda> store simple.numfetch "42"
154 PMID: 253.0.0
155 Getting description...
156 Getting Result Structure...
157 253.0.0: 2 -> 42
158 dbpmda> fetch simple.numfetch
159 PMID(s): 253.0.0
160 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
161 253.0.0 (simple.numfetch): numval: 1 valfmt: 0 vlist[]:
162 value 43
163 The value argument in the store command must be a string, which is
165 enclosed in either single quotes (') or double quotes (").
166 A profile can be specified for each instance domain which includes all,
168 some or no instances:
169 dbpmda> help profile
171 profile indom# [ all | none ]
173 profile indom# [ add | delete ] number
174 For the instance domain specified, the profile may be changed to
176 include 'all' instances, no instances, add an instance or delete
177 an instance.
178 dbpmda> profile 253.0 none
180 dbpmda> getdesc on
181 dbpmda> fetch 253.0.1
182 PMID(s): 253.0.1
183 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
184 253.0.1 (simple.color): No values returned!
185 dbpmda> profile 253.0 add 2
186 dbpmda> fetch 253.0.1
187 PMID(s): 253.0.1
188 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
189 253.0.1 (simple.color): numval: 1 valfmt: 0 vlist[]:
190 value 202
191 dbpmda> profile 253.0 add 0
192 dbpmda> fetch 253.0.1
193 PMID(s): 253.0.1
194 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
195 253.0.1 (simple.color): numval: 2 valfmt: 0 vlist[]:
196 inst [0 or ???] value 2
197 inst [2 or ???] value 203
198 dbpmda> status
199 PMDA = pmda_simple.so
201 Connection = dso
202 pmDebug = 32768 ( libpmda )
203 Timer = off
204 Dump Instance Profile state=INCLUDE, 1 profiles
206 Profile [0] indom=1061158913 [253.0] state=EXCLUDE 2 instances
207 Instances: [2] [0]
208 dbpmda> quit
209 The watch command (usage: watch filename ) opens an xterm window which
211 tails the specified log file. This window must be closed by the user
212 when no longer required.
213 The wait command is equivalent to sleep (1) and takes a single integer
215 argument.
216 The introduction of dynamic subtrees in the PMNS and PMDA_INTERFACE_4
218 in libpcp_pmda has led to additional commands being supported in dbpmda
219 to exercise the associated dynamic PMNS services. The examples below
220 are based on the sample PMDA.
221 $ dbpmda
223 dbpmda> open pipe /var/lib/pcp/pmdas/sample/pmdasample -d 29
224 Start pmdasample PMDA: /var/lib/pcp/pmdas/sample/pmdasample -d 29
225 dbpmda> children sample.secret
226 Metric: sample.secret
227 non-leaf foo
228 leaf bar
229 dbpmda> traverse sample.secret.foo
230 Metric: sample.secret.foo
231 sample.secret.foo.bar.max.redirect
232 sample.secret.foo.one
233 sample.secret.foo.two
234 sample.secret.foo.bar.three
235 sample.secret.foo.bar.four
236 sample.secret.foo.bar.grunt.five
237 sample.secret.foo.bar.grunt.snort.six
238 sample.secret.foo.bar.grunt.snort.huff.puff.seven
239 dbpmda> pmid sample.secret.foo.bar.four
240 Metric: sample.secret.foo.bar.four
241 29.0.1004
242 dbpmda> name 29.0.1006
243 PMID: 29.0.1006
244 sample.secret.foo.bar.grunt.snort.six
245 The children command returns the next name component for all the direct
247 descendants of a node within a dynamic subtree of the PMNS. The
248 related traverse command returns the full metric names for all leaf
249 nodes in the PMNS below the specified non-leaf node in a dynamic sub‐
250 tree of the PMNS.
251 The name and pmid commands exercise the translation of metric names to
253 PMIDs (and vice versa) for metrics within a dynamic subtree of the
254 PMNS.
255 If the commands children, traverse, pmid or name are used with a PMDA
257 that is not using PMDA_INTERFACE_4 or with performance metric names
258 that are not part of a dynamic subtree of the PMNS, then the PMDA would
259 be expected to return errors (PM_ERR_NAME or PM_ERR_PMID) to reflect
260 the fact that the operation is in error (outside a dynamic subtree of
261 the PMNS it is pmcd(1) and not the PMDA that is responsible for imple‐
262 menting these functions).
263 Client authentication mechanisms have been incorporated into the PMCS,
265 providing per-user (and per-connection) information that is available
266 to PMDAs. A PMDA using PMDA_INTERFACE_6 or later in libpcp_pmda is
267 able to make use of the "attribute" method to gain visibility into
268 these authenticated connections, with access to information including
269 user and group identifiers, user name, and so on. The need to exercise
270 and debug this interface has led to a new dbpmda command. The follow‐
271 ing example is based on the sample PMDA.
272 $ dbpmda
274 dbpmda> open pipe pmdasample -D AUTH -l logfile
275 Start pmdasample PMDA: pmdasample -D AUTH -l logfile
276 dbpmda> attr "username" "tanya"
277 Attribute: username=tanya
278 Success
279 dbpmda> attr 11 "0"
280 Attribute: userid=0
281 Success
282 dbpmda>
283 The attr command passes connection attributes (PCP_ATTR keys) and their
285 values into a PMDA in much the same way that PMCD would for a client
286 connection. dbpmda always passes a client context identifier of zero,
287 and while no validity checking on values is performed only recognised
288 attributes can be set.
289 In the example above the AUTH debugging option is set for the PMDA,
291 which uses this in its attribute callback and records each attribute
292 and value pair sent to it in its logfile.
293 Note that authentication checks have already been performed by PMCD by
295 the time a PMDA is presented with these attributes, so no further veri‐
296 fication is necessary by the PMDA.
297
299 A value cannot be stored into metrics of type PM_TYPE_AGGREGATE or
300 PM_TYPE_EVENT.
301 dbpmda uses fork(2) and exec(2) to attach to daemon PMDAs. dbpmda
303 makes no attempt to detect the termination of the daemon PMDA process,
304 so it is possible for a PMDA to exit unexpectedly without any notifica‐
305 tion. However, any further communication attempts with the PMDA will
306 result in errors which will indicate that the PMDA is no longer
307 responding.
308
310 ./.dbpmdarc
311 List of commands to do on startup.
312
314 Environment variables with the prefix PCP_ are used to parameterize the
315 file and directory names used by PCP. On each installation, the file
316 /etc/pcp.conf contains the local values for these variables. The
317 $PCP_CONF variable may be used to specify an alternative configuration
318 file, as described in pcp.conf(5).
319
321 gdb(1), pmcd(1), pmdbg(1), exec(2), fork(2), PMAPI(3), PMDA(3),
322 pcp.conf(5) and pcp.env(5).
323Performance Co-Pilot PCP DBPMDA(1)