sourCEntral - mobile manpages

pdf

DBPMDADBPMDA

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 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.

dbpmda accepts the following command line arguments:

−e

Echo the input to stdout. This is useful when the input is redirected from a file.

−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 Performance 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 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 five 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.

As there are no timeout constraints on a PMDA while using 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 .dbpmdarc 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 identified 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 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 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# [ 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

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 further communication attempts with the PMDA will result 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 dbpmda. 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).

pdf