'\"macro stdmacro
.\"
.\" Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH DBPMDA 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3dbpmda\f1 \- debugger for Performance Co-Pilot PMDAs
.SH SYNOPSIS
\f3dbpmda\f1
[\f3\-efiv?\f1]
[\f3\-n\f1 \f2pmnsfile\f1]
[\f3\-q\f1 \f2timeout\f1]
[\f3\-U\f1 \f2username\f1]
.SH DESCRIPTION
.B dbpmda
is an interactive interface to the interactions between a
Performance Metric Domain Agent
.RB ( PMDA (3))
and the Performance Metric Collector Daemon
.RB ( pmcd (1)).
This allows PMDAs to be attached, initialized and exercised to test for
correctness.
.PP
.B dbpmda
interactively prompts the user for commands, many of which emulate the
Protocol Data Units (PDUs) that may be sent by a
.BR pmcd (1)
process.
After running
.BR dbpmda ,
enter the command
.B help
to get a list of the available commands.
The example section below illustrates
a session using
.B dbpmda
to test a PMDA.
.PP
To simplify repetitive testing of a PMDA, the file
.I .dbpmdarc
in the current working directory can contain a list of commands that will be
executed by
.B dbpmda
on startup, before the user is prompted to enter further commands
interactively.
While processing the
.I .dbpmdarc
file, interactive mode and command echoing are enabled and then
reset at the end of the
.I .dbpmdarc
file (see the
.B \-i
and
.B \-e
command line options below).
.PP
The
.B \-f
command line option prevents startup processing of a
.I .dbpmdarc
file (if it exists).
.PP
If the system supports
.BR 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.
.PP
As there are no timeout constraints on a PMDA while using
.B dbpmda
(as compared to
.BR pmcd (1)),
another debugger like
.BR gdb (1)
can be used on the PMDA process once it has been attached to
.BR dbpmda .
.SH OPTIONS
The available command line options are:
.TP 5
\f3\-e\f1, \f3\-\-echo\-input\f1
Echo the input to
.BR stdout .
This is useful when the input is redirected from a file.
.TP
\f3\-f\f1, \f3\-\-norc\f1
Do not process the
.B .dbpmdarc
file.
.TP
\f3\-i\f1, \f3\-\-interactive\f1
Emulate interactive behavior and prompt for new commands, even if standard
input is not a tty device.
.TP
\fB\-n\fR \fIpmnsfile\fR, \fB\-\-namespace\fR=\fIpmnsfile\fR
Load an alternative Performance Metrics Name Space
.RB ( PMNS (5))
from the file
.IR pmnsfile .
.TP
\fB\-q\fR \fItimeout\fR, \fB\-\-creds\-timeout\fR=\fItimeout\fR
The pmcd to agent version exchange protocol (new in PCP 2.0 - introduced to
provide backward compatibility) uses this timeout to specify how long \f3dbpmda\f1
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
.B \-q
option allows an alternative timeout interval (which must be greater than
zero) to be specified.
The unit of time is seconds.
.TP
\fB\-U\fR \fIusername\fR, \fB\-\-username\fR=\fIusername\fR
User account under which to run
.BR dbpmda .
.TP
\fB\-v\fR, \fB\-\-valgrind\fR
Useful when running
.B dbpmda
under the control of
.BR valgrind (1)
to triage problems in a DSO PMDA.
If the
.B \-v
option is used then
.B dbpmda
will do not call
.BR dlclose (3)
before exiting, this allows
.BR valgrind (1)
to access the symbol table of the DSO PMDA when reporting which makes
debugging much easier.
.TP
\fB\-?\fR, \fB\-\-help\fR
Display usage message and exit.
.SH EXAMPLES
Below is a
.B dbpmda
session using the
.I simple
PMDA.
A
.B \.dbpmdarc
file is used to set the debugging option, open the PMDA and display the
current status of the debugger:
.PP
.nf
.ft CR
.in +0.5i
$ cat .dbpmdarc
debug libpmda
open dso pmda_simple.so simple_init 253
status
.fi
.in
.PP
When
.B dbpmda
is run, the commands in the
.B \.dbpmdarc
file are executed first:
.PP
.nf
.ft CR
.in +0.5i
$ 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>
.fi
.in
.PP
To examine the metric and instance domain metadata, the
.B desc
and
.B 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:
.PP
.nf
.ft CR
.in +0.5i
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"
.fi
.in
.PP
To test the most important component of a PMDA, the
.BR fetch ,
it is often useful to determine the time it takes the PMDA to respond.
The
.B timer
may be turned on before giving a
.BR fetch :
.PP
.nf
.ft CR
.in +0.5i
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
.fi
.in
.PP
The integer, floating point and hex translations of the values in the
.I pmResult
structure are dumped if
.B getdesc
is set to
.B off
(the default).
Setting
.B getdesc
to
.B on
also fetches the metric metadata (or
.BR 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.
.PP
Similarly, the
.B getiname
setting controls the lookup of external instance names for metrics with an
associated instance domain.
When
.B off
(the default)
the output is as above.
When
.B on
the instance ``names'' ??? are translated into their external instance names
by the PMDA and reported as below:
.PP
.nf
.ft CR
.in +0.5i
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
.fi
.in
.PP
Because the metric metadata is required to do the instance name lookup, setting
.B getiname
to
.B on
implicitly sets
.B getdesc
to
.BR on .
.PP
Note that if either
.B getdesc
or
.B getiname
are set
.B on
then each
.B 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
.BR off .
.PP
The simple PMDA also supports the
.B store
operation
which can be tested with subsequent
.B fetch
commands:
.PP
.nf
.ft CR
.in +0.5i
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
.fi
.in
.PP
The value argument in the
.B store
command must be a string, which is enclosed in either single quotes (')
or double quotes (").
.PP
A
.B profile
can be specified for each instance domain which includes all, some or no
instances:
.PP
.nf
.ft CR
.in +0.5i
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
.fi
.PP
The
.B watch
command (usage:
.B watch
.I filename
) opens an xterm window which tails the specified log file.
This window must be closed by the user when no longer required.
.PP
The
.B wait
command is equivalent to
.BR sleep (1)
and takes a single integer argument (wait time in seconds).
.PP
The introduction of dynamic subtrees in the
PMNS and PMDA_INTERFACE_4 in
.I libpcp_pmda
has led to additional commands being supported in
.B dbpmda
to exercise the associated dynamic PMNS services.
The examples below are based on the
.I sample
PMDA.
.PP
.nf
.ft CR
.in +0.5i
$ 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
.fi
.in
.PP
The
.B children
command returns the next name component for all the direct descendants
of a node within a dynamic subtree of the PMNS.
The related
.B 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.
.PP
The
.B name
and
.B pmid
commands exercise the translation of metric names to PMIDs (and vice
versa) for metrics within a dynamic subtree of the PMNS.
.PP
If the commands
.BR children ,
.BR traverse ,
.B pmid
or
.B name
are used with a PMDA that is
.B 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
.BR pmcd (1)
and not the PMDA that
is responsible for implementing these functions).
.PP
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
.I 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
.B dbpmda
command.
The following example is based on the
.I sample
PMDA.
.PP
.nf
.ft CR
.in +0.5i
$ 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>
.fi
.in
.PP
The
.B 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.
.B dbpmda
always passes a client context identifier of zero, and while no
validity checking on values is performed only recognised attributes
can be set.
.PP
In the example above the
.I 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
.IR logfile .
.PP
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.
.PP
The
.B 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
.B \-l
option to
.BR pmdbg (1)
and/or their deprecated equivalent numeric values as reported by the
.B \-ol
options to
.BR pmdbg (1).
The special ``option''
.B none
turns all debugging off and the special ``option''
.B all
enables all the debugging options.
.SH CAVEATS
A value cannot be stored into metrics of type
.B PM_TYPE_AGGREGATE
or
.BR PM_TYPE_EVENT .
.PP
.B dbpmda
uses
.BR fork (2)
and
.BR exec (2)
to attach to daemon PMDAs.
.B 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.
.SH FILES
.TP 5
.I ./.dbpmdarc
List of commands to do on startup.
.SH PCP ENVIRONMENT
Environment variables with the prefix \fBPCP_\fP are used to parameterize
the file and directory names used by PCP.
On each installation, the
file \fI/etc/pcp.conf\fP contains the local values for these variables.
The \fB$PCP_CONF\fP variable may be used to specify an alternative
configuration file, as described in \fBpcp.conf\fP(5).
.PP
For environment variables affecting PCP tools, see \fBpmGetOptions\fP(3).
.SH SEE ALSO
.BR gdb (1),
.BR pmcd (1),
.BR pmdbg (1),
.BR exec (2),
.BR fork (2),
.BR PMAPI (3),
.BR PMDA (3),
.BR pcp.conf (5),
.BR pcp.env (5)
and
.BR PMNS (5).