1DBPMDA(1) General Commands Manual DBPMDA(1)
2
6 dbpmda - debugger for Performance Co-Pilot PMDAs
7
9 $PCP_BINADM_DIR/dbpmda [-ei] [-n pmnsfile] [-q timeout]
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 As there are no timeout constraints on a PMDA while using dbpmda (as
60 compared to pmcd(1)), another debugger like dbx(1) can be used on the
61 PMDA process once it has been attached to dbpmda.
62
64 Below is a dbpmda session using the simple PMDA. A .dbpmdarc file is
65 used to set the debugging flag, open the PMDA and display the current
66 status of the debugger:
67 $ cat .dbpmdarc
69 debug libpmda
70 open dso mips_o32.pmda_simple.so simple_init 253
71 status
72 When dbpmda is run, the commands in the .dbpmdarc file are executed
74 first:
75 $ dbpmda
77 .dbpmdarc> debug libpmda
78 .dbpmdarc> open dso mips_o32.pmda_simple.so simple_init 253
79 [Fri Sep 19 10:19:55] dbpmda(11651) Debug: pmdaInit: PMDA simple DSO: Metric 0.0.1(1) matched to indom 253.0(0)
80 [Fri Sep 19 10:19:55] dbpmda(11651) Debug: pmdaInit: PMDA simple DSO: help file $PCP_PMDAS_DIR/simple/help opened
81 [Fri Sep 19 10:19:55] dbpmda(11651) Info: name = simple DSO
82 [Fri Sep 19 10:19:55] dbpmda(11651) Info: domain = 253
83 [Fri Sep 19 10:19:55] dbpmda(11651) Info: num metrics = 4
84 [Fri Sep 19 10:19:55] dbpmda(11651) Info: num indom = 1
85 [Fri Sep 19 10:19:55] dbpmda(11651) Info: direct map = 1
86 .dbpmdarc> status
87 Namespace: (default)
89 PMDA: ./mips_o32.pmda_simple.so
90 Connection: dso
91 DSO Interface Version: 2
92 PMDA PMAPI Version: 2
93 pmDebug: 32768 ( libpmda )
94 Timer: off
95 Getdesc: off
96 Dump Instance Profile state=INCLUDE, 0 profiles
98 .dbpmdarc>
100 To examine the metric and instance descriptors, the desc and instance
102 commands can be used. Metrics may be identified either by name, or
103 using the ``dotted'' notation to specify the domain, cluster and item
104 fields of a PMID. Instance domains must be identified using a ``dot‐
105 ted'' notation to specify the domain and serial fields. The syntax for
106 most commands will be displayed if the command is given without any
107 arguments:
108 dbpmda> desc 253.0.0
110 PMID: 253.0.0
111 Data Type: 32-bit unsigned int InDom: PM_INDOM_NULL 0xffffffff
112 Semantics: instant Units: none
113 dbpmda> instance
114 instance indom# [ number | name | "name" ]
115 dbpmda> instance 253.0
116 pmInDom: 253.0
117 [ 0] inst: 0 name: "red"
118 [ 1] inst: 1 name: "green"
119 [ 2] inst: 2 name: "blue"
120 To test the most important component of a PMDA, the fetch, it is often
122 useful to determine the time it takes the PMDA to respond. The timer
123 may be turned on before giving a fetch:
124 dbpmda> timer on
126 dbpmda> fetch simple.numfetch 253.0.1
127 PMID(s): 253.0.0 253.0.1
128 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 2
129 253.0.0 (simple.numfetch): numval: 1 valfmt: 0 vlist[]:
130 value 1 1.4012985e-45 0x1
131 253.0.1 (simple.color): numval: 3 valfmt: 0 vlist[]:
132 inst [0 or ???] value 1 1 1.4012985e-45 0x1
133 inst [1 or ???] value 101 1.4153114e-43 0x65
134 inst [2 or ???] value 201 2.8166099e-43 0xc9
135 Timer: 0.003921 seconds
136 dbpmda> timer off
137 The integer, floating point and hex translations of the values in the
139 pmResult structure are dumped if getdesc is set to off (the default).
140 Setting getdesc to on would result in only integer values being dumped
141 in the above fetch as the descriptor describes the metrics of 32-bit
142 unsigned integers.
143 The simple PMDA also supports the store operation which can be tested
145 with subsequent fetch commands:
146 dbpmda> store simple.numfetch "42"
148 PMID: 253.0.0
149 Getting description...
150 Getting Result Structure...
151 253.0.0: 2 -> 42
152 dbpmda> fetch simple.numfetch
153 PMID(s): 253.0.0
154 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
155 253.0.0 (simple.numfetch): numval: 1 valfmt: 0 vlist[]:
156 value 43
157 A profile can be specified for each instance domain which includes all,
159 some or no instances:
160 dbpmda> help profile
162 profile indom# [ all | none ]
164 profile indom# [ add | delete ] number
165 For the instance domain specified, the profile may be changed to
167 include 'all' instances, no instances, add an instance or delete
168 an instance.
169 dbpmda> profile 253.0 none
171 dbpmda> getdesc on
172 dbpmda> fetch 253.0.1
173 PMID(s): 253.0.1
174 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
175 253.0.1 (simple.color): No values returned!
176 dbpmda> profile 253.0 add 2
177 dbpmda> fetch 253.0.1
178 PMID(s): 253.0.1
179 pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
180 253.0.1 (simple.color): numval: 1 valfmt: 0 vlist[]:
181 value 202
182 dbpmda> profile 253.0 add 0
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: 2 valfmt: 0 vlist[]:
187 inst [0 or ???] value 2
188 inst [2 or ???] value 203
189 dbpmda> status
190 PMDA = mips_o32.pmda_simple.so
192 Connection = dso
193 pmDebug = 32768 ( libpmda )
194 Timer = off
195 Dump Instance Profile state=INCLUDE, 1 profiles
197 Profile [0] indom=1061158913 [253.0] state=EXCLUDE 2 instances
198 Instances: [2] [0]
199 dbpmda> quit
200 The watch command (usage: watch filename ) opens an xwsh window which
202 tails the specified log file. This window must be closed by the user
203 when no longer required.
204 The wait command is equivalent to sleep (1) and takes a single integer
206 argument.
207 The introduction of dynamic subtrees in the PMNS and PMDA_INTERFACE_4
209 in libpcp_pmda has led to additional commands being supported in dbpmda
210 to exercise the associated dynamic PMNS services. The examples below
211 are based on the sample PMDA.
212 $ dbpmda
214 dbpmda> open pipe /var/lib/pcp/pmdas/sample/pmdasample -d 29
215 dbpmda> Start pmdasample PMDA: /var/lib/pcp/pmdas/sample/pmdasample -d 29
216 dbpmda> children sample.secret
217 Metric: sample.secret
218 non-leaf foo
219 leaf bar
220 dbpmda> traverse sample.secret.foo
221 Metric: sample.secret.foo
222 sample.secret.foo.bar.max.redirect
223 sample.secret.foo.one
224 sample.secret.foo.two
225 sample.secret.foo.bar.three
226 sample.secret.foo.bar.four
227 sample.secret.foo.bar.grunt.five
228 sample.secret.foo.bar.grunt.snort.six
229 sample.secret.foo.bar.grunt.snort.huff.puff.seven
230 dbpmda> pmid sample.secret.foo.bar.four
231 Metric: sample.secret.foo.bar.four
232 29.0.1004
233 dbpmda> name 29.0.1006
234 PMID: 29.0.1006
235 sample.secret.foo.bar.grunt.snort.six
236 The children command returns the next name component for all the direct
238 descendents of a node within a dynamic subtree of the PMNS. The
239 related traverse command returns the full metric names for all leaf
240 nodes in the PMNS below the specified non-leaf node in a dynamic sub‐
241 tree of the PMNS.
242 The name and pmid commands exercise the translation of metric names to
244 PMIDs (and vice versa) for metrics within a dynamic subtree of the
245 PMNS.
246 If the commands children, traverse, pmid or name are used with a PMDA
248 that is not using PMDA_INTERFACE_4 or with performance metric names
249 that are not part of a dynamic subtree of the PMNS, then the PMDA would
250 be expected to return errors (PM_ERR_NAME or PM_ERR_PMID) to reflect
251 the fact that the operation is in error (outside a dynamic subtree of
252 the PMNS it is pmcd(1) and not the PMDA that is responsible for imple‐
253 menting these functions).
254
256 A value cannot be stored into a metric of type PM_TYPE_AGGREGATE.
257 dbpmda uses fork(2) and exec(2) to attach to daemon PMDAs. dbpmda
259 makes no attempt to detect the termination of the daemon PMDA process,
260 so it is possible for a PMDA to exit unexpectedly without any notifica‐
261 tion. However, any further communication attempts with the PMDA will
262 result in errors which will indicate that the PMDA is no longer
263 responding.
264 Only DSO PMDAs with the same simabi (Subprogram Interface Model ABI) as
266 the running kernel may be attached to dbpmda. ie. a machine running a
267 64-bit kernel will have a 64-bit version of dbpmda which may only be
268 attached to 64-bit DSO PMDAs. As daemon PMDAs are separate processes,
269 there are no simabi restrictions between dbpmda and daemon PMDAs.
270
272 ./.dbpmdarc
273 List of commands to do on startup.
274
276 Environment variables with the prefix PCP_ are used to parameterize the
277 file and directory names used by PCP. On each installation, the file
278 /etc/pcp.conf contains the local values for these variables. The
279 $PCP_CONF variable may be used to specify an alternative configuration
280 file, as described in pcp.conf(4).
281
283 pmcd(1), pmdbg(1), exec(2), fork(2), PMAPI(3), PMDA(3), pcp.conf(4) and
284 pcp.env(4).
285Performance Co-Pilot SGI DBPMDA(1)