dbpmda man page on RedHat

Man page or keyword search:  
man Server   29550 pages
apropos Keyword Search (all sections)
Output format
RedHat logo
[printable version]

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 Per‐
       formance Metric Domain Agent (PMDA(3)) and the Performance Metric  Col‐
       lector 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  emu‐
       late  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 ses‐
       sion 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).

       If the system supports readline(3) then this will be used to read  com‐
       mands  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	``dot‐
       ted''  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       = 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
       descendents 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  sub‐
       tree 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	imple‐
       menting 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 follow‐
       ing 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 veri‐
       fication 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 notifica‐
       tion. 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).

Performance Co-Pilot		      PCP			     DBPMDA(1)
[top]

List of man pages available for RedHat

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net