NAME
dbpmda - debugger for Performance Co-Pilot PMDAs
SYNOPSIS
$PCP_BINADM_DIR/dbpmda [-ei] [-n pmnsfile] [-q timeout]
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 dbp
mda to test a PMDA.
To simplify repetitive testing of a PMDA, the file .dbpm
darc 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.
dbpmda accepts the following command line arguments:
-e Echo the input to stdout.
-i Emulate interactive behavior and prompt for new
commands, even if standard input is not a tty
device.
-n pmnsfile
Normally dbpmda operates on the distributed Perfor
mance Metrics Name Space (PMNS), however if the -n
option is specified an alternative local PMNS is
loaded from the file pmnsfile.
-q timeout
The pmcd to agent version exchange protocol (new in
PCP 2.0 - introduced to provide backward compati
bility) uses this timeout to specify how long dbp
mda 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 five seconds, but
the -q option allows an alternative timeout inter
val (which must be greater than zero) to be speci
fied. The unit of time is seconds.
dbpmda (as compared to pmcd(1)), another debugger like
dbx(1) can be used on the PMDA process once it has been
attached to dbpmda.
EXAMPLE
Below is a dbpmda session using the simple PMDA. A .dbpm
darc file is used to set the debugging flag, open the PMDA
and display the current status of the debugger:
$ cat .dbpmdarc
debug libpmda
open dso mips_o32.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 mips_o32.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: ./mips_o32.pmda_simple.so
Connection: dso
DSO Interface Version: 2
PMDA PMAPI Version: 2
pmDebug: 32768 ( libpmda )
Timer: off
Getdesc: off
Dump Instance Profile state=INCLUDE, 0 profiles
.dbpmdarc>
To examine the metric and instance descriptors, the desc
and instance commands can be used. Metrics may be identi
fied either by name, or using the ``dotted'' notation to
specify the domain, cluster and item fields of a PMID.
Instance domains must be identified using a ``dotted''
notation to specify the domain and serial fields. The syn
tax for most commands will be displayed if the command is
given without any arguments:
dbpmda> desc 253.0.0
PMID: 253.0.0
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 would
result in only integer values being dumped in the above
fetch as the descriptor describes the metrics of 32-bit
unsigned integers.
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
A profile can be specified for each instance domain which
includes all, some or no instances:
dbpmda> help profile
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
PMDA = mips_o32.pmda_simple.so
Connection = dso
pmDebug = 32768 ( libpmda )
Timer = 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 xwsh
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.
CAVEATS
A value cannot be stored into a metric of type
PM_TYPE_AGGREGATE.
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
in errors which will indicate that the PMDA is no longer
responding.
Only DSO PMDAs with the same simabi (Subprogram Interface
Model ABI) as the running kernel may be attached to dbp
mda. ie. a machine running a 64-bit kernel will have a
64-bit version of dbpmda which may only be attached to
64-bit DSO PMDAs. As daemon PMDAs are separate processes,
there are no simabi restrictions between dbpmda and daemon
PMDAs.
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(4).
SEE ALSO
pmcd(1), pmdbg(1), exec(2), fork(2), PMAPI(3), PMDA(3),
pcp.conf(4) and pcp.env(4).
Man(1) output converted with
man2html