2. EL 8
  3. pcp-parfait-agent
  4. parfait(1)

Scroll to navigation

PARFAIT(1) 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:

The name argument specifies the mmv.* metric tree name in the PMNS(5) that will be used to identify this application.
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.
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.
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.
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:

JSON array of individual metrics, must appear at the top level.
A string which forms the dotted-form metric name, as well as the optional PCP instance name in square brackets.
An optional string providing explanatory help text for a metric.
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.
A string which will be parsed to produce the JSR-363 units for the metric. Currently bytes or milliseconds are supported.
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.
A string used to identify the Java managed bean backing this metric in the JVM (e.g. java.lang:type=Memory).
An optional string used to identify a specific attribute of a managed bean (e.g. HeapMemoryUsage).
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:

SEE ALSO

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

October 2017