NAME

       dbpmda - debugger for Performance Co-Pilot PMDAs


SYNOPSIS

       $PCP_BINADM_DIR/dbpmda [-ei] [-n pmnsfile] [-q timeout]


DESCRIPTION

       dbpmda  is  an  interactive  interface to the interactions
       between a Performance Metric Domain  Agent  (PMDA(3))  and
       the  Performance  Metric Collector Daemon (pmcd(1)).  This
       allows PMDAs to be attached, initialized and exercised  to
       test for correctness.

       dbpmda  interactively  prompts the user for commands, many
       of which emulate the Protocol Data Units (PDUs)  that  may
       be sent by a pmcd(1) process.  After running dbpmda, enter
       the command help to get a list of the available  commands.
       The example section below illustrates a session using dbp­
       mda to test a PMDA.

       To simplify repetitive testing of a PMDA, the file  .dbpm­
       darc  in  the current working directory can contain a list
       of commands that will be executed by  dbpmda  on  startup,
       before  the  user  is  prompted  to enter further commands
       interactively.

       dbpmda accepts the following command line arguments:

       -e     Echo the input to stdout.

       -i     Emulate interactive behavior  and  prompt  for  new
              commands,  even  if  standard  input  is  not a tty
              device.

       -n pmnsfile
              Normally dbpmda operates on the distributed Perfor­
              mance  Metrics Name Space (PMNS), however if the -n
              option is specified an alternative  local  PMNS  is
              loaded from the file pmnsfile.

       -q timeout
              The pmcd to agent version exchange protocol (new in
              PCP 2.0 - introduced to provide  backward  compati­
              bility)  uses this timeout to specify how long dbp­
              mda should wait before  assuming  that  no  version
              response  is coming from an agent.  If this timeout
              is reached, the agent is assumed  to  be  an  agent
              which  does  not  understand  the PCP 2.0 protocol.
              The default timeout interval is five  seconds,  but
              the  -q option allows an alternative timeout inter­
              val (which must be greater than zero) to be  speci­
              fied.  The unit of time is seconds.

       dbpmda (as compared to  pmcd(1)),  another  debugger  like
       dbx(1)  can  be  used on the PMDA process once it has been
       attached to dbpmda.


EXAMPLE

       Below is a dbpmda session using the simple PMDA. A  .dbpm­
       darc file is used to set the debugging flag, open the PMDA
       and display the current status of the debugger:

            $ cat .dbpmdarc
            debug libpmda
            open dso mips_o32.pmda_simple.so simple_init 253
            status

       When dbpmda is run, the commands in the .dbpmdarc file are
       executed first:

            $ dbpmda
            .dbpmdarc> debug libpmda
            .dbpmdarc> open dso mips_o32.pmda_simple.so simple_init 253
            [Fri Sep 19 10:19:55] dbpmda(11651) Debug: pmdaInit: PMDA simple DSO: Metric 0.0.1(1) matched to indom 253.0(0)
            [Fri Sep 19 10:19:55] dbpmda(11651) Debug: pmdaInit: PMDA simple DSO: help file $PCP_PMDAS_DIR/simple/help opened
            [Fri Sep 19 10:19:55] dbpmda(11651) Info: name        = simple DSO
            [Fri Sep 19 10:19:55] dbpmda(11651) Info: domain      = 253
            [Fri Sep 19 10:19:55] dbpmda(11651) Info: num metrics = 4
            [Fri Sep 19 10:19:55] dbpmda(11651) Info: num indom   = 1
            [Fri Sep 19 10:19:55] dbpmda(11651) Info: direct map  = 1
            .dbpmdarc> status

            Namespace:              (default)
            PMDA:                   ./mips_o32.pmda_simple.so
            Connection:             dso
            DSO Interface Version:  2
            PMDA PMAPI Version:     2
            pmDebug:                32768 ( libpmda )
            Timer:                  off
            Getdesc:                off

            Dump Instance Profile state=INCLUDE, 0 profiles

            .dbpmdarc>

       To  examine  the metric and instance descriptors, the desc
       and instance commands can be used.  Metrics may be identi­
       fied  either  by name, or using the ``dotted'' notation to
       specify the domain, cluster and item  fields  of  a  PMID.
       Instance  domains  must  be  identified using a ``dotted''
       notation to specify the domain and serial fields. The syn­
       tax  for most commands will be displayed if the command is
       given without any arguments:

            dbpmda> desc 253.0.0
            PMID: 253.0.0

                Semantics: instant  Units: none
            dbpmda> instance
            instance indom# [ number | name | "name" ]
            dbpmda> instance 253.0
            pmInDom: 253.0
            [  0] inst: 0 name: "red"
            [  1] inst: 1 name: "green"
            [  2] inst: 2 name: "blue"

       To test the most important component of a PMDA, the fetch,
       it is often useful to determine the time it takes the PMDA
       to respond.  The timer may be turned on  before  giving  a
       fetch:

            dbpmda> timer on
            dbpmda> fetch simple.numfetch 253.0.1
            PMID(s): 253.0.0 253.0.1
            pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 2
              253.0.0 (simple.numfetch): numval: 1 valfmt: 0 vlist[]:
               value 1 1.4012985e-45 0x1
              253.0.1 (simple.color): numval: 3 valfmt: 0 vlist[]:
                inst [0 or ???] value 1 1 1.4012985e-45 0x1
                inst [1 or ???] value 101 1.4153114e-43 0x65
                inst [2 or ???] value 201 2.8166099e-43 0xc9
            Timer: 0.003921 seconds
            dbpmda> timer off

       The  integer,  floating  point and hex translations of the
       values in the pmResult structure are dumped if getdesc  is
       set  to  off  (the  default).  Setting getdesc to on would
       result in only integer values being dumped  in  the  above
       fetch  as  the  descriptor describes the metrics of 32-bit
       unsigned integers.

       The simple PMDA also supports the  store  operation  which
       can be tested with subsequent fetch commands:

            dbpmda> store simple.numfetch "42"
            PMID: 253.0.0
            Getting description...
            Getting Result Structure...
            253.0.0: 2 -> 42
            dbpmda> fetch simple.numfetch
            PMID(s): 253.0.0
            pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
              253.0.0 (simple.numfetch): numval: 1 valfmt: 0 vlist[]:
               value 43

       A  profile can be specified for each instance domain which
       includes all, some or no instances:

            dbpmda> help profile

            profile indom# [ add | delete ] number

            For the instance domain specified, the profile may be changed to
            include 'all' instances, no instances, add an instance or delete
            an instance.

            dbpmda> profile 253.0 none
            dbpmda> getdesc on
            dbpmda> fetch 253.0.1
            PMID(s): 253.0.1
            pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
              253.0.1 (simple.color): No values returned!
            dbpmda> profile 253.0 add 2
            dbpmda> fetch 253.0.1
            PMID(s): 253.0.1
            pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
              253.0.1 (simple.color): numval: 1 valfmt: 0 vlist[]:
               value 202
            dbpmda> profile 253.0 add 0
            dbpmda> fetch 253.0.1
            PMID(s): 253.0.1
            pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
              253.0.1 (simple.color): numval: 2 valfmt: 0 vlist[]:
                inst [0 or ???] value 2
                inst [2 or ???] value 203
            dbpmda> status

            PMDA       = mips_o32.pmda_simple.so
            Connection = dso
            pmDebug    = 32768 ( libpmda )
            Timer      = off

            Dump Instance Profile state=INCLUDE, 1 profiles
                    Profile [0] indom=1061158913 [253.0] state=EXCLUDE 2 instances
                            Instances: [2] [0]
            dbpmda> quit

       The watch command (usage: watch filename ) opens  an  xwsh
       window  which  tails  the specified log file.  This window
       must be closed by the user when no longer required.

       The wait command is equivalent to sleep (1)  and  takes  a
       single integer argument.


CAVEATS

       A   value   cannot   be  stored  into  a  metric  of  type
       PM_TYPE_AGGREGATE.

       dbpmda uses fork(2) and exec(2) to attach to daemon PMDAs.
       dbpmda  makes  no attempt to detect the termination of the
       daemon PMDA process, so it is possible for a PMDA to  exit
       unexpectedly   without   any  notification.  However,  any

       in  errors  which will indicate that the PMDA is no longer
       responding.

       Only DSO PMDAs with the same simabi (Subprogram  Interface
       Model  ABI)  as the running kernel may be attached to dbp­
       mda.  ie. a machine running a 64-bit kernel  will  have  a
       64-bit  version  of  dbpmda  which may only be attached to
       64-bit DSO PMDAs.  As daemon PMDAs are separate processes,
       there are no simabi restrictions between dbpmda and daemon
       PMDAs.


FILES

       ./.dbpmdarc
                 List of commands to do on startup.


PCP ENVIRONMENT

       Environment variables with the prefix  PCP_  are  used  to
       parameterize the file and directory names used by PCP.  On
       each installation, the  file  /etc/pcp.conf  contains  the
       local  values for these variables.  The $PCP_CONF variable
       may be used to specify an alternative configuration  file,
       as described in pcp.conf(4).


SEE ALSO

       pmcd(1),  pmdbg(1),  exec(2),  fork(2), PMAPI(3), PMDA(3),
       pcp.conf(4) and pcp.env(4).


Man(1) output converted with man2html