PARFAIT(1)

NAME
parfait - Java instrumentation for Performance Co-Pilot (PCP)

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

DESCRIPTION
The parfait wrapper script provides instrumentation for an unmodified Java application. It is a front end to the Parfait https://github.com/performancecopilot/parfait modules which developers use to access instrumentation from Java applications.

The parfait script is limited to exposing performance metrics that it can find indirectly, such as via JMX.

In order to be exported to the PCP Memory Mapped Values PMDA (see pmdammv(1) for details) these metrics must first be categorized with PCP metadata.

This is performed by configuration of the parfait-agent.jar file used by parfait. In the simplest form the configuration is sourced from files in the /etc/parfait directory. Additional JMX managed beans can be added to the default set through configuration files in the /etc/parfait directory.

If this directory is empty, does not exist, or is otherwise inaccessible, a minimal configuration is read from within the resources of the parfait-agent.jar file.

Configuration files must be in the JSON format - refer to the CONFIGURATION section below for details of the file format.

There are two forms of instrumentation available from the parfait script - direct instrumentation (agent mode) or via a JMX server (proxy mode).

See the EXAMPLES section below for an example invocation for each mode.

OPTIONS
The command line options available are:

-n / --name name
    The name argument specifies the mmv.* metric tree name in the PMNS(5) that will be used to identify this application.

-c / --cluster identifier
    The numeric performance metric cluster identifier to be used to uniquely identify this application. A value of zero is the default, and causes the MMV PMDA to simply use the next available number.

-i / --interval msec
    Delay between sampling (JMX values in particular) to refresh the values exported to PCP, in milliseconds. The default value is 1000 (1 second) and the minimum allowed value is 250 milliseconds.

-j / --jmxserver / --connect hostname:port
    Connect to the JMX server listening on the specified hostname and port number as the source of JMX metrics. This option allows proxying of metrics from a separate process, instead of the default -javaagent mode of operation.

-s / --startup msec
    Maximum startup time in which JMX values are still being created, before exporting as memory mapped values, in milliseconds. The default value is 5000 (5 seconds).

EXAMPLES
The following examples can be installed locally using the parfait-examples package.

The affects of each example invocation below can be seen using any PCP client tool, such as

•   pminfo -f mmv

•   pmprobe -v mmv

•   pmchart

•   pmie

•   pmrep

•   [... and many others ...]

The default mode of operation involves directly running the Java process to be instrumented with a javaagent:

•   java -Dparfait.name=sleep -javaagent:/usr/share/java/parfait/parfait.jar -jar /usr/share/java/parfait/sleep.jar Main

The alternative is the proxy mode, where an already running Java process is instrumented using its JMX server. To start the Java application with a JMX server exposed, use the following options:

•   java -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9875 -Dcom.sun.management.jmxremote.local.only=true -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -jar /usr/share/java/parfait/sleep.jar Main

The JMX server is then allowing access from instrumentation by parfait, which can be invoked as follows:

•   java -Dparfait.name=sleep -jar /usr/share/java/parfait/parfait.jar -connect=localhost:9875

CONFIGURATION
The statically configured metrics used by parfait-agent are configured using JSON configuration files. The default used when no files are present below /etc/parfait is:

•   jvm.json https://github.com/performancecopilot/parfait/tree/master/parfait-agent/src/main/resources/jvm.json

This provides a handy reference for the semantic elements of the JSON configuration, which are:

The metrics array
    JSON array of individual metrics, must appear at the top level.

Metric name
    A string which forms the dotted-form metric name, as well as the optional PCP instance name in square brackets.

Metric description
    An optional string providing explanatory help text for a metric.

Metric semantics
    An optional string with one of the following values: constant or discrete; count or counter; and gauge, instant or instantaneous. These map directly to the PCP metric semantics. The value instantaneous is the default.

Metric units
    A string which will be parsed to produce the JSR-363 units for the metric. Currently bytes or milliseconds are supported.

Whether the metric is optional
    A boolean (default: false) which flags whether this metric must exist in the JVM. Certain metrics only appear in some situations, or some versions of the JVM, these should be marked as optional metrics.

Managed bean name mBeanName
    A string used to identify the Java managed bean backing this metric in the JVM (e.g. java.lang:type=Memory).

Managed bean attribute name mBeanAttributeName
    An optional string used to identify a specific attribute of a managed bean (e.g. HeapMemoryUsage).

Managed bean composite data item (mBeanCompositeDataItem)
    An optional string used to further classify an individual value of the managed bean attribute (e.g. max).

FILES

$PCP-TMP-DIR/mmv/*
    default local of memory mapped values files created by parfait.

/etc/parfait/*.json
    configuration files defining metrics in the format described above.

LINKS
Parfait https://github.com/performancecopilot/parfait:

•   Default metrics https://github.com/performancecopilot/parfait/tree/master/parfait-agent/src/main/resources/jvm.json

Performance Co-Pilot http://pcp.io:

•   PCPIntro http://man7.org/linux/man-pages/man1/pcpintro.1.html

•   pmcd http://man7.org/linux/man-pages/man1/pmcd.1.html

•   pmchart http://man7.org/linux/man-pages/man1/pmchart.1.html

•   pmdammv http://man7.org/linux/man-pages/man1/pmdammv.1.html

•   pmie http://man7.org/linux/man-pages/man1/pmie.1.html

•   pminfo http://man7.org/linux/man-pages/man1/pminfo.1.html

•   pmprobe http://man7.org/linux/man-pages/man1/pmprobe.1.html

•   pmrep http://man7.org/linux/man-pages/man1/pmrep.1.html

•   PMAPI http://man7.org/linux/man-pages/man3/PMAPI.3.html

•   PMNS http://man7.org/linux/man-pages/man5/pmns.5.html

SEE ALSO
PCPIntro(1), pmcd(1), pmchart(1) pmdammv(1) pmie(1), pminfo(1), pmprobe(1), pmrep(1), PMAPI(3), and PMNS(5).