--- name: "dbpmda" section: "1" platform: "linux" package: "pcp" version: "7.2.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/dbpmda" --- # dbpmda(1) debugger for Performance Co-Pilot PMDAs ## 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)](/PMDA/3.md)) and the Performance Metric Collector Daemon ([**pmcd**(1)](/pmcd/1.md)). 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)](/pmcd/1.md) 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)](/readline/3.md) 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)](/pmcd/1.md)), another debugger like [**gdb**(1)](/gdb/1.md) 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)](/PMNS/5.md)) 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)](/valgrind/1.md) to triage problems in a DSO PMDA. If the **-v** option is used then **dbpmda** will do not call [**dlclose**(3)](/dlclose/3.md) before exiting, this allows [**valgrind**(1)](/valgrind/1.md) 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)](/sleep/1.md) `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)](/pmcd/1.md) `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)](/pmdbg/1.md) `and/or their deprecated equivalent numeric values as reported by the` **-ol** `options to` [**pmdbg**(1)](/pmdbg/1.md). ```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)](/fork/2.md) `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 than for end-users.` *debug* `is a comma separated list of debugging options; use` [**pmdbg**(1)](/pmdbg/1.md) `with the` **-l** `option to obtain` `a list of the available debugging options and their meaning.` ## SEE ALSO [**gdb**(1)](/gdb/1.md), [**pmcd**(1)](/pmcd/1.md), [**pmdbg**(1)](/pmdbg/1.md), **exec**(2), [**fork**(2)](/fork/2.md), [**PMAPI**(3)](/PMAPI/3.md), [**PMDA**(3)](/PMDA/3.md), [**pcp.conf**(5)](/pcp.conf/5.md), [**pcp.env**(5)](/pcp.env/5.md) `and` [**PMNS**(5)](/PMNS/5.md).