Knowledge Base

How do I enable Java Flight Recorder and view the Results

Java Flight Recorder can be used to capture low level Java properties and run-time data about Java processes, for example Neo4j.

Per https://docs.oracle.com/javase/8/docs/technotes/guides/troubleshoot/tooldescr002.html

The Java Flight Recorder (JFR) is a commercial feature. You can use it for free on developer desktops/laptops, and for
evaluation purposes in test, development, and production environments. However, to enable JFR on a production server,
you require a commercial license. Using JMC UI for other purposes on the JDK does not require a commercial license.

JFR can be activated by configuring JVM options within a Java application at startup or by using the jcmd tool for a running Java application. The commands and options available will depend on the supported JVM in use based on the Neo4j version. The JMC documentation here links to the documentation of various JDK versions for example and may be helpful when the need for additional options arises.

To enable the Java Flight Recorder at the start of Neo4j service, the following JVM options should be added to the neo4j.conf and then Neo4j needs to be restarted for these changes to take effect. The JFR.dump commands discussed later can be used to dump the contents once enabled.

For 3.x

dbms.jvm.additional=-XX:+UnlockCommercialFeatures
dbms.jvm.additional=-XX:+FlightRecorder
dbms.jvm.additional=-XX:FlightRecorderOptions=defaultrecording=true,settings=profile

For 4.x

dbms.jvm.additional=-XX:StartFlightRecording=settings=profile

For 5.x

server.jvm.additional=-XX:StartFlightRecording=settings=profile

To begin a time based recording, at the command line run:

$ $JAVA_HOME/jcmd <pid> JFR.start duration=3600s filename=myrecording.jfr settings=/usr/lib/jvm/java-8-oracle/jre/lib/jfr/profile.jfc

replacing <pid> with the linux pid for the Neo4j process (i.e. ps -eaf | grep java).

The inclusion of duration=3600s, should have resulted in a recording that spanned 1 hour and this file will be written to at the completion of the 1 hour run.

The reference to filename=myrecording.jfr above, describes the output file to be produced. When no path is defined the resultant file will be recorded at $NEO4J_HOME. Alternatively one could define filename with a full path reference, for example filename=/tmp/myrecording.jfr.

Also the location of the profile.jfc may be at a different directory/path for your given install. The expected path is in $JRE_HOME/lib/jfr.

If you do not know how long to run the recording since the issue may be intermittent, run:

$ $JAVA_HOME/jcmd <pid> JFR.start settings=/usr/lib/jvm/java-8-oracle/jre/lib/jfr/profile.jfc

and to which this will report

3962:
Started recording 1. No limit (duration/maxsize/maxage) in use.

Use JFR.dump recording=1 filename=FILEPATH to copy recording data to file.

and to then dump the recording to a file run:

$ jcmd <pid> JFR.dump recording=<recording #> filename=<filename>

and then to completely stop the recording, though this does not dump the contents of the recording to a file run:

$ jcmd <pid> JFR.stop recording=<recording #>

(Note: The recording= option in the above commands is not used in the JDK versions for Neo4j 4.x and 5x and instead one can use name= . )

To view the results start Java Mission Control ($JAVA/HOME/jmc). This will launch a Java app as detailed below. Note, if you are connected via Putty or a Telnet client this may not launch. As an alternative, MobaXterm can be used.

The resultant Java Flight Recorder file can be analyzed using Java Mission Control. To start Java Mission Control run $JAVA_HOME/jmc. Once started, using menu File / Open File, one can then browse to the flight recorder file.

image