dbpmda(1) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | CAVEATS | FILES | PCP ENVIRONMENT | SEE ALSO | COLOPHON

DBPMDA(1)                General Commands Manual               DBPMDA(1)

NAME         top

       dbpmda - debugger for Performance Co-Pilot PMDAs

SYNOPSIS         top

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

DESCRIPTION         top

       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         top

       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         top

       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         top

       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         top

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

PCP ENVIRONMENT         top

       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         top

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

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at 
       ⟨http://www.pcp.io/⟩.  If you have a bug report for this manual
       page, send it to [email protected].  This page was obtained from the
       project's upstream Git repository
       ⟨https://github.com/performancecopilot/pcp.git⟩ on 2024-06-14.
       (At that time, the date of the most recent commit that was found
       in the repository was 2024-06-14.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       [email protected]

Performance Co-Pilot               PCP                         DBPMDA(1)

Pages that refer to this page: pmdakernel(1)pmdaopenmetrics(1)pmda(3)