dbpmda(1)
NAME
dbpmda - debugger for Performance Co-Pilot PMDAs
SYNOPSIS
dbpmda [-efi] [-n pmnsfile] [-q timeout] [-U username]
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. 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 arguments 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. 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. -U username User account under which to run dbpmda. 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.
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 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: 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
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
PMDA = 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 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.
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 debug flag 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.
CAVEATS
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
./.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).
SEE ALSO
gdb(1), pmcd(1), pmdbg(1), exec(2), fork(2), PMAPI(3), PMDA(3), pcp.conf(5) and pcp.env(5).
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
