1PARFAIT(1)                                                          PARFAIT(1)
2
3
4

NAME

6       parfait - Java instrumentation for Performance Co-Pilot (PCP)
7

SYNOPSIS

9       parfait   [-n/--name   name]  [-c/--cluster  id]  [-i/--interval  msec]
10       [-s/--startup  delay]   [-j/--jmxserver   --connect   host:port]   [--]
11       [javaargs ...]
12

DESCRIPTION

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

OPTIONS

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

EXAMPLES

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

CONFIGURATION

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

FILES

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

SEE ALSO

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)
Impressum