Provided by: pcp_6.0.3-1_amd64 bug

NAME

       dbpmda - debugger for Performance Co-Pilot PMDAs

SYNOPSIS

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

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 options below).

       The -f command line option prevents startup processing of a .dbpmdarc file (if it exists).

       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.

       As there are no timeout constraints on a PMDA while using dbpmda (as compared to pmcd(1)),
       another debugger like gdb(1) can be used on the PMDA process once it has been attached  to
       dbpmda.

OPTIONS

       The available command line options are:

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

       -f, --norc
            Do not process the .dbpmdarc file.

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

       -n pmnsfile, --namespace=pmnsfile
            Load an alternative Performance Metrics Name Space (PMNS(5)) from the file pmnsfile.

       -q timeout, --creds-timeout=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 three 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.

       -U username, --username=username
            User account under which to run dbpmda.

       -v, --valgrind
            Useful when running dbpmda under the control of valgrind(1) to triage problems  in  a
            DSO  PMDA.   If  the -v option is used then dbpmda will do not call dlclose(3) before
            exiting, this allows valgrind(1) to access the symbol table  of  the  DSO  PMDA  when
            reporting which makes debugging much easier.

       -?, --help
            Display usage message and exit.

EXAMPLES

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

            $ cat .dbpmdarc
            debug libpmda
            open dso 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 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:                   ./pmda_simple.so
            Connection:             dso
            DSO Interface Version:  7
            PMDA PMAPI Version:     2
            Debug options:          libpmda
            Timer:                  off
            Getdesc:                off
            Getiname:               off

            Dump Instance Profile state=INCLUDE, 0 profiles

            .dbpmdarc>

       To examine the metric and instance domain metadata, the desc and instance commands can  be
       used.   Metrics may be identified either by name, or using the numeric ``dotted'' notation
       to specify the domain, cluster and item fields  of  a  PMID.   Instance  domains  must  be
       identified  using  a  numeric ``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 also fetches the
       metric metadata (or pmDesc) and this would result in only integer values being  dumped  in
       the  above  fetch  as  the metric metadata describes the metric type to be 32-bit unsigned
       integers.

       Similarly, the getiname setting controls the lookup of external instance names for metrics
       with  an associated instance domain.  When off (the default) the output is as above.  When
       on the instance ``names'' ??? are translated into their external  instance  names  by  the
       PMDA and reported as below:

            dbpmda> getiname on
            dbpmda> fetch simple.color
            PMID(s): 253.0.1
            pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
              253.0.1 (simple.color): numval: 3 valfmt: 0 vlist[]:
                inst [0 or "red"] value 4
                inst [1 or "green"] value 104
                inst [2 or "blue"] value 204

       Because  the  metric metadata is required to do the instance name lookup, setting getiname
       to on implicitly sets getdesc to on.

       Note that if either getdesc or getiname are set on then  each  fetch  involves  additional
       calls on the PMDA.  For a PMDA under development this may not be a good idea, which is why
       both settings default to off.

       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

       The  value  argument  in  the  store command must be a string, which is enclosed in either
       single quotes (') or double quotes (").

       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

            Namespace:              (default)
            PMDA:                   ./pmda_simple.so
            Connection:             dso
            DSO Interface Version:  7
            PMDA PMAPI Version:     2
            Debug options:          (none)
            Timer:                  off
            Getdesc:                off
            Getiname:               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 xterm 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 (wait  time
       in seconds).

       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
            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 descendants 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).

       Client  authentication mechanisms have been incorporated into the PMCS, providing per-user
       (and  per-connection)  information  that  is   available   to   PMDAs.    A   PMDA   using
       PMDA_INTERFACE_6  or later in libpcp_pmda is able to make use of the "attribute" method to
       gain visibility into these authenticated connections, with access to information including
       user  and  group  identifiers,  user name, and so on.  The need to exercise and debug this
       interface has led to a new dbpmda command.  The following example is based on  the  sample
       PMDA.

            $ dbpmda
            dbpmda> open pipe pmdasample -D AUTH -l logfile
            Start pmdasample PMDA: pmdasample -D AUTH -l logfile
            dbpmda> attr "username" "tanya"
            Attribute: username=tanya
            Success
            dbpmda> attr 11 "0"
            Attribute: userid=0
            Success
            dbpmda>

       The attr command passes connection attributes (PCP_ATTR keys) and their values into a PMDA
       in much the same way that PMCD would for a client  connection.   dbpmda  always  passes  a
       client  context  identifier of zero, and while no validity checking on values is performed
       only recognised attributes can be set.

       In the example above the AUTH debugging option is set for the PMDA, which uses this in its
       attribute callback and records each attribute and value pair sent to it in its logfile.

       Note  that authentication checks have already been performed by PMCD by the time a PMDA is
       presented with these attributes, so no further verification is necessary by the PMDA.

       The debug command takes one or more debug options separated  by  whitespace  or  a  comma.
       This  can  be  used to selectively enable debugging output from various modules of the PCP
       libraries that the PMDA will be linked with.  If the option is prefixed by a  minus  ``-''
       the  corresponding  debugging option is disabled.  The options are the same debug names as
       reported by the -l option to pmdbg(1) and/or their deprecated equivalent numeric values as
       reported  by the -ol options to pmdbg(1).  The special ``option'' none turns all debugging
       off and the special ``option'' all enables all the debugging options.

CAVEATS

       A value cannot be stored into metrics of type PM_TYPE_AGGREGATE or PM_TYPE_EVENT.

       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.

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(5).

       For environment variables affecting PCP tools, see pmGetOptions(3).

SEE ALSO

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