1PARFAIT(1) PARFAIT(1)
2
3
4
6 parfait - Java instrumentation for Performance Co-Pilot (PCP)
7
9 parfait [-n/--name name] [-c/--cluster id] [-i/--interval msec]
10 [-s/--startup delay] [-j/--jmxserver --connect host:port] [--]
11 [javaargs ...]
12
14 The parfait wrapper script provides instrumentation for an unmodified
15 Java application. It is a front end to the Parfait
16 https://github.com/performancecopilot/parfait modules which developers
17 use to access instrumentation from Java applications.
18
19 The parfait script is limited to exposing performance metrics that it
20 can find indirectly, such as via JMX.
21
22 In order to be exported to the PCP Memory Mapped Values PMDA (see
23 pmdammv(1) for details) these metrics must first be categorized with
24 PCP metadata.
25
26 This is performed by configuration of the parfait-agent.jar file used
27 by parfait. In the simplest form the configuration is sourced from
28 files in the /etc/parfait directory. Additional JMX managed beans can
29 be added to the default set through configuration files in the
30 /etc/parfait directory.
31
32 If this directory is empty, does not exist, or is otherwise inaccessi‐
33 ble, a minimal configuration is read from within the resources of the
34 parfait-agent.jar file.
35
36 Configuration files must be in the JSON format - refer to the CONFIGU‐
37 RATION section below for details of the file format.
38
39 There are two forms of instrumentation available from the parfait
40 script - direct instrumentation (agent mode) or via a JMX server (proxy
41 mode).
42
43 See the EXAMPLES section below for an example invocation for each mode.
44
46 The command line options available are:
47
48 -n / --name name
49 The name argument specifies the mmv.* metric tree name in the
50 PMNS(5) that will be used to identify this application.
51
52 -c / --cluster identifier
53 The numeric performance metric cluster identifier to be used to
54 uniquely identify this application. A value of zero is the
55 default, and causes the MMV PMDA to simply use the next avail‐
56 able number.
57
58 -i / --interval msec
59 Delay between sampling (JMX values in particular) to refresh the
60 values exported to PCP, in milliseconds. The default value is
61 1000 (1 second) and the minimum allowed value is 250 millisec‐
62 onds.
63
64 -j / --jmxserver / --connect hostname:port
65 Connect to the JMX server listening on the specified hostname
66 and port number as the source of JMX metrics. This option allows
67 proxying of metrics from a separate process, instead of the
68 default -javaagent mode of operation.
69
70 -s / --startup msec
71 Maximum startup time in which JMX values are still being cre‐
72 ated, before exporting as memory mapped values, in milliseconds.
73 The default value is 5000 (5 seconds).
74
76 The following examples can be installed locally using the parfait-exam‐
77 ples package.
78
79 The affects of each example invocation below can be seen using any PCP
80 client tool, such as
81
82 · pminfo -f mmv
83
84 · pmprobe -v mmv
85
86 · pmchart
87
88 · pmie
89
90 · pmrep
91
92 · [... and many others ...]
93
94
95
96 The default mode of operation involves directly running the Java
97 process to be instrumented with a javaagent:
98
99 · java -Dparfait.name=sleep -javaagent:/usr/share/java/parfait/par‐
100 fait.jar -jar /usr/share/java/parfait/sleep.jar Main
101
102
103
104 The alternative is the proxy mode, where an already running Java
105 process is instrumented using its JMX server. To start the Java appli‐
106 cation with a JMX server exposed, use the following options:
107
108 · java -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxre‐
109 mote.port=9875 -Dcom.sun.management.jmxremote.local.only=true
110 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.manage‐
111 ment.jmxremote.ssl=false -jar /usr/share/java/parfait/sleep.jar
112 Main
113
114
115
116 The JMX server is then allowing access from instrumentation by parfait,
117 which can be invoked as follows:
118
119 · java -Dparfait.name=sleep -jar /usr/share/java/parfait/parfait.jar
120 -connect=localhost:9875
121
122
123
125 The statically configured metrics used by parfait-agent are configured
126 using JSON configuration files. The default used when no files are
127 present below /etc/parfait is:
128
129 · jvm.json https://github.com/performancecopilot/parfait/tree/mas‐
130 ter/parfait-agent/src/main/resources/jvm.json
131
132
133
134 This provides a handy reference for the semantic elements of the JSON
135 configuration, which are:
136
137 The metrics array
138 JSON array of individual metrics, must appear at the top level.
139
140 Metric name
141 A string which forms the dotted-form metric name, as well as the
142 optional PCP instance name in square brackets.
143
144 Metric description
145 An optional string providing explanatory help text for a metric.
146
147 Metric semantics
148 An optional string with one of the following values: constant or
149 discrete; count or counter; and gauge, instant or instantaneous.
150 These map directly to the PCP metric semantics. The value
151 instantaneous is the default.
152
153 Metric units
154 A string which will be parsed to produce the JSR-363 units for
155 the metric. Currently bytes or milliseconds are supported.
156
157 Whether the metric is optional
158 A boolean (default: false) which flags whether this metric must
159 exist in the JVM. Certain metrics only appear in some situa‐
160 tions, or some versions of the JVM, these should be marked as
161 optional metrics.
162
163 Managed bean name mBeanName
164 A string used to identify the Java managed bean backing this
165 metric in the JVM (e.g. java.lang:type=Memory).
166
167 Managed bean attribute name mBeanAttributeName
168 An optional string used to identify a specific attribute of a
169 managed bean (e.g. HeapMemoryUsage).
170
171 Managed bean composite data item (mBeanCompositeDataItem)
172 An optional string used to further classify an individual value
173 of the managed bean attribute (e.g. max).
174
176 $PCP-TMP-DIR/mmv/*
177 default local of memory mapped values files created by parfait.
178
179 /etc/parfait/*.json
180 configuration files defining metrics in the format described
181 above.
182
184 Parfait https://github.com/performancecopilot/parfait:
185
186 · Default metrics https://github.com/performancecopilot/par‐
187 fait/tree/master/parfait-agent/src/main/resources/jvm.json
188
189
190
191 Performance Co-Pilot http://pcp.io:
192
193 · PCPIntro http://man7.org/linux/man-pages/man1/pcpintro.1.html
194
195 · pmcd http://man7.org/linux/man-pages/man1/pmcd.1.html
196
197 · pmchart http://man7.org/linux/man-pages/man1/pmchart.1.html
198
199 · pmdammv http://man7.org/linux/man-pages/man1/pmdammv.1.html
200
201 · pmie http://man7.org/linux/man-pages/man1/pmie.1.html
202
203 · pminfo http://man7.org/linux/man-pages/man1/pminfo.1.html
204
205 · pmprobe http://man7.org/linux/man-pages/man1/pmprobe.1.html
206
207 · pmrep http://man7.org/linux/man-pages/man1/pmrep.1.html
208
209 · PMAPI http://man7.org/linux/man-pages/man3/PMAPI.3.html
210
211 · PMNS http://man7.org/linux/man-pages/man5/pmns.5.html
212
213
214
216 PCPIntro(1), pmcd(1), pmchart(1) pmdammv(1) pmie(1), pminfo(1),
217 pmprobe(1), pmrep(1), PMAPI(3), and PMNS(5).
218
219
220
221 October 2017 PARFAIT(1)