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.
