1PMDABASH(1) General Commands Manual PMDABASH(1)
2
6 pmdabash - Bourne-Again SHell trace performance metrics domain agent
7
9 $PCP_PMDAS_DIR/bash/pmdabash [-C] [-d domain] [-l logfile] [-I inter‐
10 val] [-t timeout] [-U username] configfile
11
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 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 This requires bash version 4 or later.
23 A brief description of the pmdabash command line options follows:
25 -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 -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 -s Amount of time (in seconds) between subsequent evaluations of the
38 shell trace file descriptor(s). The default is 2 seconds.
39 -m Maximum amount of memory to be allowed for each event queue (one
41 per traced process). The default is 2 megabytes.
42 -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
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 # cd $PCP_PMDAS_DIR/bash
52 # ./Install
53 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 If you want to undo the installation, do the following as root:
59 # cd $PCP_PMDAS_DIR/bash
61 # ./Remove
62 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
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 #!/bin/sh
72 source $PCP_DIR/etc/pcp.env
73 source $PCP_SHARE_DIR/lib/bashproc.sh
74 pcp_trace on $@ # enable tracing
76 echo "awoke, $count"
77 pcp_trace off # disable tracing
79 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 $ 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 When an instrumented script is running, the generation of event records
97 can be verified using the pmevent(1) command, as follows:
98 $ 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
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
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
151 bash(1), pmevent(1) and pmcd(1).
152Performance Co-Pilot PCP PMDABASH(1)