1PARFAIT(1) PARFAIT(1)
2
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 The parfait script is limited to exposing performance metrics that it
20 can find indirectly, such as via JMX.
21 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 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 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 Configuration files must be in the JSON format - refer to the CONFIGU‐
37 RATION section below for details of the file format.
38 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 See the EXAMPLES section below for an example invocation for each mode.
44
46 The command line options available are:
47 -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 -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 -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 -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 -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 The affects of each example invocation below can be seen using any PCP
80 client tool, such as
81 · pminfo -f mmv
83 · pmprobe -v mmv
85 · pmchart
87 · pmie
89 · pmrep
91 · [... and many others ...]
93 The default mode of operation involves directly running the Java
97 process to be instrumented with a javaagent:
98 · java -Dparfait.name=sleep -javaagent:/usr/share/java/parfait/par‐
100 fait.jar -jar /usr/share/java/parfait/sleep.jar Main
101 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 · 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 The JMX server is then allowing access from instrumentation by parfait,
117 which can be invoked as follows:
118 · java -Dparfait.name=sleep -jar /usr/share/java/parfait/parfait.jar
120 -connect=localhost:9875
121
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 · jvm.json https://github.com/performancecopilot/parfait/tree/mas‐
130 ter/parfait-agent/src/main/resources/jvm.json
131 This provides a handy reference for the semantic elements of the JSON
135 configuration, which are:
136 The metrics array
138 JSON array of individual metrics, must appear at the top level.
139 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 Metric description
145 An optional string providing explanatory help text for a metric.
146 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 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 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 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 Managed bean attribute name mBeanAttributeName
168 An optional string used to identify a specific attribute of a
169 managed bean (e.g. HeapMemoryUsage).
170 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 /etc/parfait/*.json
180 configuration files defining metrics in the format described
181 above.
182
184 Parfait https://github.com/performancecopilot/parfait:
185 · Default metrics https://github.com/performancecopilot/par‐
187 fait/tree/master/parfait-agent/src/main/resources/jvm.json
188 Performance Co-Pilot http://pcp.io:
192 · PCPIntro http://man7.org/linux/man-pages/man1/pcpintro.1.html
194 · pmcd http://man7.org/linux/man-pages/man1/pmcd.1.html
196 · pmchart http://man7.org/linux/man-pages/man1/pmchart.1.html
198 · pmdammv http://man7.org/linux/man-pages/man1/pmdammv.1.html
200 · pmie http://man7.org/linux/man-pages/man1/pmie.1.html
202 · pminfo http://man7.org/linux/man-pages/man1/pminfo.1.html
204 · pmprobe http://man7.org/linux/man-pages/man1/pmprobe.1.html
206 · pmrep http://man7.org/linux/man-pages/man1/pmrep.1.html
208 · PMAPI http://man7.org/linux/man-pages/man3/PMAPI.3.html
210 · PMNS http://man7.org/linux/man-pages/man5/pmns.5.html
212
216 PCPIntro(1), pmcd(1), pmchart(1) pmdammv(1) pmie(1), pminfo(1),
217 pmprobe(1), pmrep(1), PMAPI(3), and PMNS(5).
218 October 2017 PARFAIT(1)