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 arguments
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       dbpmda accepts the following command line arguments:
39
40       -e     Echo  the  input  to  stdout.   This is useful when the input is
41              redirected from a file.
42
43       -i     Emulate interactive behavior and prompt for new  commands,  even
44              if standard input is not a tty device.
45
46       -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
51       -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
62       -U username
63              User account under which to run dbpmda.
64
65       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

EXAMPLE

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
74            $ cat .dbpmdarc
75            debug libpmda
76            open dso pmda_simple.so simple_init 253
77            status
78
79       When  dbpmda  is  run,  the commands in the .dbpmdarc file are executed
80       first:
81
82            $ 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
94            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
103            Dump Instance Profile state=INCLUDE, 0 profiles
104
105            .dbpmdarc>
106
107       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
115            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
127       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
131            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
144       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
150       The simple PMDA also supports the store operation which can  be  tested
151       with subsequent fetch commands:
152
153            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
164       The  value  argument  in  the  store command must be a string, which is
165       enclosed in either single quotes (') or double quotes (").
166
167       A profile can be specified for each instance domain which includes all,
168       some or no instances:
169
170            dbpmda> help profile
171
172            profile indom# [ all | none ]
173            profile indom# [ add | delete ] number
174
175            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
179            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
200            PMDA       = pmda_simple.so
201            Connection = dso
202            pmDebug    = 32768 ( libpmda )
203            Timer      = off
204
205            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
210       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
214       The  wait command is equivalent to sleep (1) and takes a single integer
215       argument.
216
217       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
222            $ 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
246       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
252       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
256       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
264       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
273            $ 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
284       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
290       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
294       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

CAVEATS

299       A value cannot be stored into  metrics  of  type  PM_TYPE_AGGREGATE  or
300       PM_TYPE_EVENT.
301
302       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

FILES

310       ./.dbpmdarc
311                 List of commands to do on startup.
312

PCP ENVIRONMENT

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

SEE ALSO

321       gdb(1),  pmcd(1),  pmdbg(1),  exec(2),  fork(2),   PMAPI(3),   PMDA(3),
322       pcp.conf(5) and pcp.env(5).
323
324
325
326Performance Co-Pilot                  PCP                            DBPMDA(1)
Impressum