Skip to content

Latest commit

 

History

History
219 lines (162 loc) · 7.71 KB

PARFAIT.1.md

File metadata and controls

219 lines (162 loc) · 7.71 KB
Raw

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

SYNOPSIS

parfait [-n name] [-c id] [-i msec] [-s delay] [[--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 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.

The available managed beans from a running java(1) application can be explored using standard Java tools like jconsole(1), when JMX access has been setup as in the EXAMPLES section below.

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 a sample invocation for both modes.

OPTIONS

The command line options available are:

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

  • -c identifier, --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 msec, --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).

  • -h / --help: Show a brief usage message and exit.

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
  • pmrep
  • pmie
  • [... and many others ...]

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

  • parfait --name sleep -- -jar /usr/share/java/parfait/sleep.jar

Behind the scenes this runs:

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

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

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

  • parfait --name sleep --connect localhost:9875

Behind the scenes this runs:

  • 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:

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. Acceptable unit strings include: s, seconds, ms, milliseconds, µs, microseconds, ns, nanoseconds, B, byte, bytes, KiB, Kbyte, MiB, Mbyte, GiB, Gbyte, TiB, Tbyte, EiB, Ebyte, as well as none, one and the empty string.

  • 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).

ENVIRONMENT

The contents of the environment variable PARFAIT_JAVA_OPTS, if any, are inserted into the java command line before the -javaagent argument and before any arguments in javaargs.

FILES

  • $PCP_TMP_DIR/mmv/*: memory mapped values files created by parfait.
  • /etc/parfait/*.json: configuration files defining metrics in the format described above.

LINKS

Parfait:

Performance Co-Pilot:

SEE ALSO

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