# dbpmda

## NAME



           **dbpmda** - debugger for Performance Co-Pilot PMDAs
    


## SYNOPSIS



           **dbpmda**[**-D** _debug_] [**-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_XXXX 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).
    


## DEBUGGING OPTIONS



           The **-D** or **--debug** option enables the output of additional
           diagnostics on _stderr_ to help triage problems, although the
           information is sometimes cryptic and primarily intended to provide
           guidance for developers rather end-users.  _debug_ is a comma
           separated list of debugging options; use pmdbg(1) with the **-l**
           option to obtain a list of the available debugging options and
           their meaning.
    


* * *