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.sh
73 pcp_trace on $@ # enable tracing
75 echo "awoke, $count"
76 pcp_trace off # disable tracing
78 The tracing can be enabled and disabled any number of times by the
80 script. On successful installation of the agent, several metrics will
81 be available:
82 $ pminfo bash
84 bash.xtrace.numclients
85 bash.xtrace.maxmem
86 bash.xtrace.queuemem
87 bash.xtrace.count
88 bash.xtrace.records
89 bash.xtrace.parameters.pid
90 bash.xtrace.parameters.parent
91 bash.xtrace.parameters.lineno
92 bash.xtrace.parameters.function
93 bash.xtrace.parameters.command
94 When an instrumented script is running, the generation of event records
96 can be verified using the pmevent(1) command, as follows:
97 $ pmevent -t 1 -x '' bash.xtrace.records
99 host: localhost
100 samples: all
101 bash.xtrace.records["4538 ./test-trace.sh 1 2 3"]: 5 event records
102 10:00:05.000 --- event record [0] flags 0x19 (point,id,parent) ---
103 bash.xtrace.parameters.pid 4538
104 bash.xtrace.parameters.parent 4432
105 bash.xtrace.parameters.lineno 43
106 bash.xtrace.parameters.command "true"
107 10:00:05.000 --- event record [1] flags 0x19 (point,id,parent) ---
108 bash.xtrace.parameters.pid 4538
109 bash.xtrace.parameters.parent 4432
110 bash.xtrace.parameters.lineno 45
111 bash.xtrace.parameters.command "(( count++ ))"
112 10:00:05.000 --- event record [2] flags 0x19 (point,id,parent) ---
113 bash.xtrace.parameters.pid 4538
114 bash.xtrace.parameters.parent 4432
115 bash.xtrace.parameters.lineno 46
116 bash.xtrace.parameters.command "echo 'awoke, 3'"
117 10:00:05.000 --- event record [3] flags 0x19 (point,id,parent) ---
118 bash.xtrace.parameters.pid 4538
119 bash.xtrace.parameters.parent 4432
120 bash.xtrace.parameters.lineno 47
121 bash.xtrace.parameters.command "tired 2"
122 10:00:05.000 --- event record [4] flags 0x19 (point,id,parent) ---
123 bash.xtrace.parameters.pid 4538
124 bash.xtrace.parameters.parent 4432
125 bash.xtrace.parameters.lineno 38
126 bash.xtrace.parameters.function "tired"
127 bash.xtrace.parameters.command "sleep 2"
128
130 $PCP_PMCDCONF_PATH
131 command line options used to launch pmdabash
132 $PCP_PMDAS_DIR/bash/help
133 default help text file for the bash metrics
134 $PCP_PMDAS_DIR/bash/Install
135 installation script for the pmdabash agent
136 $PCP_PMDAS_DIR/bash/Remove
137 undo installation script for pmdabash
138 $PCP_LOG_DIR/pmcd/bash.log
139 default log file for error messages and other information
140 from pmdabash
141
143 Environment variables with the prefix PCP_ are used to parameterize the
144 file and directory names used by PCP. On each installation, the file
145 /etc/pcp.conf contains the local values for these variables. The
146 $PCP_CONF variable may be used to specify an alternative configuration
147 file, as described in pcp.conf(5).
148
150 bash(1), pmevent(1) and pmcd(1).
151Performance Co-Pilot PCP PMDABASH(1)