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

NAME

6       dbpmda - debugger for Performance Co-Pilot PMDAs
7

SYNOPSIS

9       dbpmda [-efi?]  [-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
29       below).
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  -
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
71       -U username, --username=username
72            User account under which to run dbpmda.
73
74       -?, --help
75            Display usage message and exit.
76

EXAMPLES

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
82            $ cat .dbpmdarc
83            debug libpmda
84            open dso pmda_simple.so simple_init 253
85            status
86
87       When dbpmda is run, the commands in the  .dbpmdarc  file  are  executed
88       first:
89
90            $ 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
102            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
111            Dump Instance Profile state=INCLUDE, 0 profiles
112
113            .dbpmdarc>
114
115       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
123            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
135       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
139            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
152       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
158       The  simple  PMDA also supports the store operation which can be tested
159       with subsequent fetch commands:
160
161            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
172       The value argument in the store command must  be  a  string,  which  is
173       enclosed in either single quotes (') or double quotes (").
174
175       A profile can be specified for each instance domain which includes all,
176       some or no instances:
177
178            dbpmda> help profile
179
180            profile indom# [ all | none ]
181            profile indom# [ add | delete ] number
182
183            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
187            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
208            PMDA       = pmda_simple.so
209            Connection = dso
210            pmDebug    = 32768 ( libpmda )
211            Timer      = off
212
213            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
218       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
222       The wait command is equivalent to sleep (1) and takes a single  integer
223       argument.
224
225       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
230            $ 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
254       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
260       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
264       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
272       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
281            $ 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
292       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
298       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
302       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

CAVEATS

307       A  value  cannot  be  stored  into metrics of type PM_TYPE_AGGREGATE or
308       PM_TYPE_EVENT.
309
310       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

FILES

318       ./.dbpmdarc
319                 List of commands to do on startup.
320

PCP ENVIRONMENT

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
328       For environment variables affecting PCP tools, see pmGetOptions(3).
329

SEE ALSO

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).
333
334
335
336Performance Co-Pilot                  PCP                            DBPMDA(1)
Impressum