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