1DBPMDA(1)                   General Commands Manual                  DBPMDA(1)
2
3
4

NAME

6       dbpmda - debugger for Performance Co-Pilot PMDAs
7

SYNOPSIS

9       dbpmda [-efiv?]  [-n pmnsfile] [-q timeout] [-U username]
10

DESCRIPTION

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
17       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
23       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
31       The -f command line option prevents startup processing of  a  .dbpmdarc
32       file (if it exists).
33
34       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
38       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

OPTIONS

43       The available command line options are:
44
45       -e, --echo-input
46            Echo  the input to stdout.  This is useful when the input is redi‐
47            rected from a file.
48
49       -f, --norc
50            Do not process the .dbpmdarc file.
51
52       -i, --interactive
53            Emulate interactive behavior and prompt for new commands, even  if
54            standard input is not a tty device.
55
56       -n pmnsfile, --namespace=pmnsfile
57            Load  an alternative Performance Metrics Name Space (PMNS(5)) from
58            the file pmnsfile.
59
60       -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
71       -U username, --username=username
72            User account under which to run dbpmda.
73
74       -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
81       -?, --help
82            Display usage message and exit.
83

EXAMPLES

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
89            $ cat .dbpmdarc
90            debug libpmda
91            open dso pmda_simple.so simple_init 253
92            status
93
94       When dbpmda is run, the commands in the  .dbpmdarc  file  are  executed
95       first:
96
97            $ 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
109            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
119            Dump Instance Profile state=INCLUDE, 0 profiles
120
121            .dbpmdarc>
122
123       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
131            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
143       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
147            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
160       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
167       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
173            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
182       Because the metric metadata is required to do the instance name lookup,
183       setting getiname to on implicitly sets getdesc to on.
184
185       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
189       The  simple  PMDA also supports the store operation which can be tested
190       with subsequent fetch commands:
191
192            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
203       The value argument in the store command must be a string, which is  en‐
204       closed in either single quotes (') or double quotes (").
205
206       A profile can be specified for each instance domain which includes all,
207       some or no instances:
208
209            dbpmda> help profile
210
211            profile indom# [ all | none ]
212            profile indom# [ add | delete ] number
213
214            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
218            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
239            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
249            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
254       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
258       The wait command is equivalent to sleep(1) and takes a  single  integer
259       argument (wait time in seconds).
260
261       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
266            $ 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
290       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
296       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
300       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
308       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
317            $ 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
328       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
334       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
338       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
342       The  debug  command takes one or more debug options separated by white‐
343       space or a comma.  This can be used to selectively  enable  or  disable
344       debugging  output  from  various  modules of the PCP libraries that the
345       PMDA will be linked with.  The options are the same debug names as  re‐
346       ported  by the -l option to pmdbg(1) and/or their deprecated equivalent
347       numeric values as reported by the -ol options to pmdbg(1).  The special
348       ``option''  none turns all debugging off and the special ``option'' all
349       enables all the debugging options.
350

CAVEATS

352       A value cannot be stored into  metrics  of  type  PM_TYPE_AGGREGATE  or
353       PM_TYPE_EVENT.
354
355       dbpmda  uses  fork(2)  and  exec(2)  to attach to daemon PMDAs.  dbpmda
356       makes no attempt to detect the termination of the daemon PMDA  process,
357       so it is possible for a PMDA to exit unexpectedly without any notifica‐
358       tion.  However, any further communication attempts with the  PMDA  will
359       result  in  errors  which  will indicate that the PMDA is no longer re‐
360       sponding.
361

FILES

363       ./.dbpmdarc
364            List of commands to do on startup.
365

PCP ENVIRONMENT

367       Environment variables with the prefix PCP_ are used to parameterize the
368       file  and  directory names used by PCP.  On each installation, the file
369       /etc/pcp.conf contains the  local  values  for  these  variables.   The
370       $PCP_CONF  variable may be used to specify an alternative configuration
371       file, as described in pcp.conf(5).
372
373       For environment variables affecting PCP tools, see pmGetOptions(3).
374

SEE ALSO

376       gdb(1),  pmcd(1),  pmdbg(1),  exec(2),  fork(2),   PMAPI(3),   PMDA(3),
377       pcp.conf(5), pcp.env(5) and PMNS(5).
378
379
380
381Performance Co-Pilot                  PCP                            DBPMDA(1)
Impressum