parfait man page

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

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

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:

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

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:

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.

See Also

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

Info

October 2017