OpenJ9 provides some powerful command line options for troubleshooting problems with Java applications at runtime.
– The -Xdump option is used to control the use of dump agents, which produce dump files such as Java dumps, heap dumps, and system (core) dumps.
– The -Xtrace option can be used to trace Java applications, methods, and internal operations in the VM.
However, with power comes complexity and you need only to type java -Xdump:help on the command line to illustrate this point. Each option has a myriad of sub-options that can be combined together to provide very fine control over what to dump or trace.
Getting the syntax correct can be something of a black art, and unless you have been working with the VM for some time, you might easily fall foul of a curly brace or a colon.
To help you diagnose problems with your Java applications we’re pleased to introduce option builder tools for the -Xdump and -Xtrace commands. Each tool consists of a GUI that has radio buttons and input fields to cover all the typical dump and trace scenarios. As you select the actions that you want to take to identify the root cause of your problem, option builder constructs the command line syntax that you need. When you have finished making your selection you can simply copy the command to your clipboard and paste it directly to your command line.
Here are a couple of examples that illustrate how complex debugging scenarios might be and how the option builder tools can help you create the command line more easily.
Example 1: Using the option builder for -Xdump
You are receiving a NoClassDefFoundError for a specific class, and you don’t know why. You would like to investigate the class loader and class path that’s being used, and look for any other potential issues in the various objects involved.
The best way to achieve this is to open a system dump in the Eclipse Memory Analyzer Tool (MAT). Java dumps and snap dumps can also contain useful information, so you probably want to generate those too. The tricky part is to generate the dumps at just the right time, which is the exact moment the NoClassDefFoundError is thrown.
The -Xdump option allows you to trigger dumps on a variety of different events, one of which is the moment an Exception or Error is thrown. This particular event can be filtered on the Exception or Error message and/or the name of the method from which it is thrown.
In this example we use the message filter, because NoClassDefFoundError messages contain the name of the class that couldn’t be found. For this example, the missing class is com.mycompany.internals.ImportantClass. The following option triggers a Java dump, system dump, and snap trace when the NoClassDefFoundError
is thrown, for the first 3 occurrences only:
-Xdump:system+java+snap:events=throw+systhrow,filter=java/lang/NoClassDefFoundError,msg_filter="com.mycompany.internals.ImportantClass",range=1..3,request=exclusive+prepwalk+serial+preempt
To see this option in the tool, click here.
Example 2: Using the option builder for -Xtrace
One of your application methods, com.mycompany.internals.ImportantClass.veryImportantMethod(), is producing unexpected results intermittently, and you would like to see exactly what execution path is being taken inside it, how it is being called, and by whom.
The following -Xtrace option traces calls to all methods in the package com.mycompany.internals.*, including arguments and return values, but only when we are inside a call to com.mycompany.internals.ImportantClass.veryImportantMethod(). The option syntax also records a stack trace every time com.mycompany.internals.ImportantClass.veryImportantMethod() is called. The trace output is written to a binary trace file called importantMethod_[PID].trc, with a size limit of 100MB. Finally, all default tracepoints are disabled to keep the output nice and clean.
-Xtrace:none,maximal=mt,methods=com/mycompany/internals/*(),resumecount=1,trigger=method{com/mycompany/internals/ImportantClass.veryImportantMethod,resumethis,suspendthis},trigger=method{com/mycompany/internals/ImportantClass.veryImportantMethod,jstacktrace},output={"importantMethod_%p.trc",100m}
To see this option in the tool, click here.
Both examples demonstrate the unwieldy command line syntax required to troubleshoot these scenarios and how the option builder tools make light work of them.
Although hover help is available for fields in the GUI, we recommend that you use the option builder tools in conjunction with the OpenJ9 user documentation, where you can refer to the detailed descriptions for the options. The topics and the tools can be found at the following links:
– -Xdump option
– -Xtrace option
So the next time you need to generate dump files or trace output to troubleshoot a problem, give the option builder tools a try. We’d love to hear your feedback.
Authors note: The option builder tools were developed by Paul Cheeseman, an Eclipse Foundation contributor who has 17 years experience working in a senior support role at IBM. Many thanks to Paul for sharing his expertise by turning his hand to javascript!
