Unix/Linux Go Back    


CentOS 7.0 - man page for dbpmda (centos section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


DBPMDA(1)										DBPMDA(1)

NAME
       dbpmda - debugger for Performance Co-Pilot PMDAs

SYNOPSIS
       dbpmda [-ei] [-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 illus-
       trates a session using dbpmda to test a PMDA.

       To simplify repetitive testing of a PMDA, the file .dbpmdarc in the current working direc-
       tory 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).

       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 spec-
       ify  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  met-
       rics 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       = 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.

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

       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_INTER-
       FACE_6 or later in libpcp_pmda is able to make use of the "attribute" method to gain visi-
       bility 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
	    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>

       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 config-
       uration 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).

Performance Co-Pilot			       PCP					DBPMDA(1)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 08:01 AM.