NAME

jfrrecord - records a Java Flight Recorder (JFR) profile of a running OX middleware node.

SYNOPSIS

jfrrecord -f file [--overwrite] [-d duration] [--settings default|profile] [--method-timing filters] [--cpu-time] -A adminUser -P adminPassword [-H jmxHost] [-p jmxPort] [-l jmxLogin] [-s jmxPassword]

DESCRIPTION

This command line tool records a JFR profile on a running middleware node for a fixed duration and writes it to a local file. It needs no restart and no agent. Use it to find CPU hot spots and lock contention, which a thread dump only shows as a snapshot.

The middleware records for the given duration, then sends the data over the JMX connection. The file is written on the host running this tool, and nothing is left on the middleware's host. Open the file with JDK Mission Control or the jfr tool of a JDK, e.g. jfr summary recording.jfr or jfr print --events jdk.ExecutionSample recording.jfr.

Safeguards:

• Only one recording runs per node. A second request fails until the first one is done.
• A recording always stops after its duration, at most 10 minutes, and its size is capped at 256 MB.
• If the tool is terminated, the recording is discarded. If the tool is killed, the middleware discards the recording once it has not been accessed for 2 minutes.
• The recording contains no system properties, environment variables, JVM arguments, process command lines or agent options, since these may carry secrets.

A profile still reveals class names, thread names and host names of the node, so the tool always requires the master administrator's credentials.

Method timing

--method-timing counts and times the invocations of the given methods (event jdk.MethodTiming). The JVM instruments these methods for as long as the recording runs. The instrumented code calls into the package jdk.jfr.tracing, so the OSGi framework has to delegate that package to the JVM:

org.osgi.framework.bootdelegation=jdk.jfr.tracing

The config.ini template shipped with the middleware sets this. With a custom config.ini, or when org.osgi.framework.bootdelegation is also passed as a system property, make sure the value contains jdk.jfr.tracing. Otherwise the middleware rejects --method-timing, since every timed method would fail.

OPTIONS

-f, --file file : The path name of the file to write the recording to; e.g. "/tmp/recording.jfr". The file is written where this tool runs

--overwrite : Overwrite the file if it already exists

-d, --duration duration : How long to record, in seconds ("90" or "90s") or minutes ("5m"). Default is 60 seconds, maximum is 10 minutes

--settings settings : The JFR configuration: "default" (default, low overhead) or "profile" (finer sampling, more overhead)

--method-timing filters : Times invocations of the given methods (event jdk.MethodTiming). Semicolon-separated fully qualified class names, each optionally followed by "::" and a method name; e.g. "com.openexchange.drive.impl.DriveServiceImpl::syncFolders". At most 10 filters

--cpu-time : Additionally samples CPU time (event jdk.CPUTimeSample, experimental). Linux only

-A, --adminuser adminUser : Master admin user name

-P, --adminpass adminPassword : Master admin password

-H, --host jmxHost : The optional JMX host (default:localhost)

-l, --login jmxLogin : The optional JMX login (if JMX authentication is enabled)

-p, --port jmxPort : The optional JMX port (default:9999)

-s, --password jmxPassword : The optional JMX password (if JMX authentication is enabled)

-h, --help : Prints a help text

--responsetimeout : The optional response timeout in seconds when reading data from server (default: 0s; infinite)

EXAMPLES

jfrrecord -A oxadminmaster -P secret -f /tmp/recording.jfr

Records for 60 seconds with low overhead.

jfrrecord -A oxadminmaster -P secret -f /tmp/recording.jfr -d 5m --settings profile

Records for 5 minutes with finer sampling.

jfrrecord -A oxadminmaster -P secret -f /tmp/drive.jfr -d 2m --method-timing "com.openexchange.drive.impl.DriveServiceImpl::syncFolders"

Records for 2 minutes and times every invocation of syncFolders. Show the result with jfr print --events jdk.MethodTiming /tmp/drive.jfr.