diff options
Diffstat (limited to 'man/man1/dbpmda.1')
| -rw-r--r-- | man/man1/dbpmda.1 | 495 |
1 files changed, 495 insertions, 0 deletions
diff --git a/man/man1/dbpmda.1 b/man/man1/dbpmda.1 new file mode 100644 index 0000000..9d31a06 --- /dev/null +++ b/man/man1/dbpmda.1 @@ -0,0 +1,495 @@ +'\"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\-ei\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 +.I \-i +and +.I \-e +command line arguments below). +.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 +.B dbpmda +accepts the following command line arguments: +.TP +.B \-e +Echo the input to +.BR stdout . +This is useful when the input is redirected from a file. +.TP +.B \-i +Emulate interactive behavior and prompt for new commands, even if standard +input is not a tty device. +.TP +\f3\-n\f1 \f2pmnsfile\f1 +Normally +.B dbpmda +operates on the distributed Performance Metrics Name Space (PMNS), however if +the +.B \-n +option is specified an alternative local PMNS is loaded from the file +.IR pmnsfile . +.TP +\f3\-q\f1 \f2timeout\f1 +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 five 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 +\f3\-U\f1 \f2username\f1 +User account under which to run +.BR dbpmda . +.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 EXAMPLE +Below is a +.B dbpmda +session using the +.I simple +PMDA. A +.B \.dbpmdarc +file is used to set the debugging flag, open the PMDA and display the +current status of the debugger: +.PP +.nf +.ft CW +.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 CW +.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: 2 +PMDA PMAPI Version: 2 +pmDebug: 32768 ( libpmda ) +Timer: off +Getdesc: off + +Dump Instance Profile state=INCLUDE, 0 profiles + +\&.dbpmdarc> +.fi +.in +.PP +To examine the metric and instance descriptors, the +.B desc +and +.B 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: +.PP +.nf +.ft CW +.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 CW +.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 +would result in only integer values being dumped in the above fetch as the +descriptor describes the metrics of 32-bit unsigned integers. +.PP +The simple PMDA also supports the +.B store +operation +which can be tested with subsequent +.B fetch +commands: +.PP +.nf +.ft CW +.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 +A +.B profile +can be specified for each instance domain which includes all, some or no +instances: +.PP +.nf +.ft CW +.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 + +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 +.fi +.PP +The +.B watch +command (usage: +.B watch +.I filename +) opens an xwsh 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 +.B sleep (1) +and takes a single integer argument. +.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 CW +.in +0.5i +$ dbpmda +dbpmda> open pipe /var/lib/pcp/pmdas/sample/pmdasample \-d 29 +dbpmda> 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 CW +.in +0.5i +$ dbpmda +dbpmda> open pipe pmdasample \-D AUTH \-l logfile +dbpmda> 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 +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 +.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. +.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 10 +.I ./.dbpmdarc +List of commands to do on startup. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +.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) +and +.BR pcp.env (5). |