Man Linux: Main Page and Category List

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 dbpmda to test a PMDA.

       To simplify repetitive testing of a PMDA, the  file  .dbpmdarc  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.  While processing the .dbpmdarc file,
       interactive mode and command echoing are enabled and then reset at  the
       end  of  the  .dbpmdarc  file (see the -i and -e command line arguments
       below).

       If the system supports readline(3) then  this  will  be  used  to  read
       commands  when  input is from a tty device, so history and command line
       editing are available.

       dbpmda accepts the following command line arguments:

       -e     Echo the input to stdout.  This is  useful  when  the  input  is
              redirected from a file.

       -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 Performance  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 compatibility) uses this timeout
              to specify how long dbpmda 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
              interval (which must be greater than zero) to be specified.  The
              unit of time is seconds.

       As there are no timeout constraints on a PMDA while  using  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  .dbpmdarc  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 identified  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 syntax
       for most commands will be displayed if the command is given without any
       arguments:

            dbpmda> desc 253.0.0
            PMID: 253.0.0
                Data Type: 32-bit unsigned int  InDom: PM_INDOM_NULL 0xffffffff
                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# [ all | none ]
            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.

       The introduction of dynamic subtrees in the PMNS  and  PMDA_INTERFACE_4
       in libpcp_pmda has led to additional commands being supported in dbpmda
       to exercise the associated dynamic PMNS services.  The  examples  below
       are based on the sample PMDA.

            $ dbpmda
            dbpmda> open pipe /var/lib/pcp/pmdas/sample/pmdasample -d 29
            dbpmda> Start pmdasample PMDA: /var/lib/pcp/pmdas/sample/pmdasample -d 29
            dbpmda> children sample.secret
            Metric: sample.secret
               non-leaf foo
                   leaf bar
            dbpmda> traverse sample.secret.foo
            Metric: sample.secret.foo
               sample.secret.foo.bar.max.redirect
               sample.secret.foo.one
               sample.secret.foo.two
               sample.secret.foo.bar.three
               sample.secret.foo.bar.four
               sample.secret.foo.bar.grunt.five
               sample.secret.foo.bar.grunt.snort.six
               sample.secret.foo.bar.grunt.snort.huff.puff.seven
            dbpmda> pmid sample.secret.foo.bar.four
            Metric: sample.secret.foo.bar.four
               29.0.1004
            dbpmda> name 29.0.1006
            PMID: 29.0.1006
               sample.secret.foo.bar.grunt.snort.six

       The children command returns the next name component for all the direct
       descendents of a node within  a  dynamic  subtree  of  the  PMNS.   The
       related  traverse  command  returns  the full metric names for all leaf
       nodes in the PMNS below  the  specified  non-leaf  node  in  a  dynamic
       subtree of the PMNS.

       The  name and pmid commands exercise the translation of metric names to
       PMIDs (and vice versa) for metrics within  a  dynamic  subtree  of  the
       PMNS.

       If  the  commands children, traverse, pmid or name are used with a PMDA
       that is not using PMDA_INTERFACE_4 or  with  performance  metric  names
       that are not part of a dynamic subtree of the PMNS, then the PMDA would
       be expected to return errors (PM_ERR_NAME or  PM_ERR_PMID)  to  reflect
       the  fact  that the operation is in error (outside a dynamic subtree of
       the PMNS it is pmcd(1)  and  not  the  PMDA  that  is  responsible  for
       implementing these functions).

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 further communication attempts with the PMDA
       will  result  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 dbpmda.  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).