1PMDABASH(1)                 General Commands Manual                PMDABASH(1)
2
3
4

NAME

6       pmdabash - Bourne-Again SHell trace performance metrics domain agent
7

SYNOPSIS

9       $PCP_PMDAS_DIR/bash/pmdabash  [-C]  [-d domain] [-l logfile] [-I inter‐
10       val] [-t timeout] [-U username] configfile
11

DESCRIPTION

13       pmdabash is an experimental Performance  Metrics  Domain  Agent  (PMDA)
14       which  exports  "xtrace"  events  from  a traced bash(1) process.  This
15       includes the command execution information that would usually  be  sent
16       to standard error with the set -x option to the shell.
17
18       Event  metrics are exported showing each command executed, the function
19       name and line number in the script, and a timestamp.  Additionally, the
20       process identifier for the shell and its parent process are exported.
21
22       This requires bash version 4 or later.
23
24       A brief description of the pmdabash command line options follows:
25
26       -d   It  is absolutely crucial that the performance metrics domain num‐
27            ber specified here is unique  and  consistent.   That  is,  domain
28            should  be  different for every PMDA on the one host, and the same
29            domain number should be used for the same PMDA on all hosts.
30
31       -l   Location of the log file.  By default, a log file  named  bash.log
32            is  written  in  the current directory of pmcd(1) when pmdabash is
33            started, i.e.  $PCP_LOG_DIR/pmcd.  If the log file cannot be  cre‐
34            ated  or  is not writable, output is written to the standard error
35            instead.
36
37       -s   Amount of time (in seconds) between subsequent evaluations of  the
38            shell trace file descriptor(s).  The default is 2 seconds.
39
40       -m   Maximum  amount  of memory to be allowed for each event queue (one
41            per traced process).  The default is 2 megabytes.
42
43       -U   User account under which to run the agent.   The  default  is  the
44            unprivileged  "pcp"  account  in  current  versions of PCP, but in
45            older versions the superuser account ("root") was used by default.
46

INSTALLATION

48       In order for a host to export the names, help text and values  for  the
49       bash performance metrics, do the following as root:
50
51            # cd $PCP_PMDAS_DIR/bash
52            # ./Install
53
54       As  soon as an instrumented shell script (see INSTRUMENTATION selection
55       below) is run, with tracing enabled, new metric values will appear - no
56       further setup of the agent is required.
57
58       If you want to undo the installation, do the following as root:
59
60            # cd $PCP_PMDAS_DIR/bash
61            # ./Remove
62
63       pmdabash  is launched by pmcd(1) and should never be executed directly.
64       The Install and  Remove  scripts  notify  pmcd(1)  when  the  agent  is
65       installed or removed.
66

INSTRUMENTATION

68       In  order  to allow the flow of event data between a bash(1) script and
69       pmdabash, the script should take the following actions:
70
71            #!/bin/sh
72            source $PCP_DIR/etc/pcp.env
73            source $PCP_SHARE_DIR/lib/bashproc.sh
74
75            pcp_trace on $@       # enable tracing
76            echo "awoke, $count"
77
78            pcp_trace off         # disable tracing
79
80       The tracing can be enabled and disabled any  number  of  times  by  the
81       script.   On successful installation of the agent, several metrics will
82       be available:
83
84            $ pminfo bash
85            bash.xtrace.numclients
86            bash.xtrace.maxmem
87            bash.xtrace.queuemem
88            bash.xtrace.count
89            bash.xtrace.records
90            bash.xtrace.parameters.pid
91            bash.xtrace.parameters.parent
92            bash.xtrace.parameters.lineno
93            bash.xtrace.parameters.function
94            bash.xtrace.parameters.command
95
96       When an instrumented script is running, the generation of event records
97       can be verified using the pmevent(1) command, as follows:
98
99            $ pmevent -t 1 -x '' bash.xtrace.records
100            host:      localhost
101            samples:   all
102            bash.xtrace.records["4538 ./test-trace.sh 1 2 3"]: 5 event records
103              10:00:05.000 --- event record [0] flags 0x19 (point,id,parent) ---
104                bash.xtrace.parameters.pid 4538
105                bash.xtrace.parameters.parent 4432
106                bash.xtrace.parameters.lineno 43
107                bash.xtrace.parameters.command "true"
108              10:00:05.000 --- event record [1] flags 0x19 (point,id,parent) ---
109                bash.xtrace.parameters.pid 4538
110                bash.xtrace.parameters.parent 4432
111                bash.xtrace.parameters.lineno 45
112                bash.xtrace.parameters.command "((  count++  ))"
113              10:00:05.000 --- event record [2] flags 0x19 (point,id,parent) ---
114                bash.xtrace.parameters.pid 4538
115                bash.xtrace.parameters.parent 4432
116                bash.xtrace.parameters.lineno 46
117                bash.xtrace.parameters.command "echo 'awoke, 3'"
118              10:00:05.000 --- event record [3] flags 0x19 (point,id,parent) ---
119                bash.xtrace.parameters.pid 4538
120                bash.xtrace.parameters.parent 4432
121                bash.xtrace.parameters.lineno 47
122                bash.xtrace.parameters.command "tired 2"
123              10:00:05.000 --- event record [4] flags 0x19 (point,id,parent) ---
124                bash.xtrace.parameters.pid 4538
125                bash.xtrace.parameters.parent 4432
126                bash.xtrace.parameters.lineno 38
127                bash.xtrace.parameters.function "tired"
128                bash.xtrace.parameters.command "sleep 2"
129

FILES

131       $PCP_PMCDCONF_PATH
132                 command line options used to launch pmdabash
133       $PCP_PMDAS_DIR/bash/help
134                 default help text file for the bash metrics
135       $PCP_PMDAS_DIR/bash/Install
136                 installation script for the pmdabash agent
137       $PCP_PMDAS_DIR/bash/Remove
138                 undo installation script for pmdabash
139       $PCP_LOG_DIR/pmcd/bash.log
140                 default  log  file  for  error messages and other information
141                 from pmdabash
142

PCP ENVIRONMENT

144       Environment variables with the prefix PCP_ are used to parameterize the
145       file  and  directory names used by PCP.  On each installation, the file
146       /etc/pcp.conf contains the  local  values  for  these  variables.   The
147       $PCP_CONF  variable may be used to specify an alternative configuration
148       file, as described in pcp.conf(5).
149

SEE ALSO

151       bash(1), pmevent(1) and pmcd(1).
152
153
154
155Performance Co-Pilot                  PCP                          PMDABASH(1)
Impressum