JDK-7104647 : Adding a diagnostic command framework
  • Type: Enhancement
  • Component: core-svc
  • Sub-Component: tools
  • Affected Version: 7u4
  • Priority: P3
  • Status: Closed
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2011-10-25
  • Updated: 2023-11-10
  • Resolved: 2012-02-09
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 7 JDK 8
7u4 b10Fixed 8Fixed
Related Reports
Relates :  
Relates :  
Description
Background
The JRockit JDK has a framework for issuing diagnostics commands to the JVM. The framework has a command line tool called jrcmd, a JMX interface and a ctrl-break handler with configuration file and signal handler.

The goal of this CR is to provide a similar feature to HotSpot with:
     - a diagnostics command framework that supports a command line tool and JMX interface.
     - a support for public, closed/licensed and hidden diagnostic commands.
     - a command line tool called jcmd that allows execution of all diagnostic commands.
     - an equivalent to the JRockit JDK diagnostics command “version” and "help" must be implemented to demonstrate and test the features of the framework
     
Note:
Other diagnostics commands that can be executed with this framework are not in scope of this CR.

Comments
The remote JMX functionality was later added back by https://bugs.openjdk.org/browse/JDK-7150256 See: https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/DiagnosticCommandMBean.html
10-11-2023

JDK-7145925: Removing remote access to diagnostic commands in the HotSpotDiagnosticMBean is a closed JBS issue and basically removed the remote access to diagnostic commands in the HotSpotDiagnosticMBean again: http://hg.openjdk.java.net/jdk8/tl/jdk/rev/20d39a0e6fdc
10-11-2023

EVALUATION http://hg.openjdk.java.net/lambda/lambda/hotspot/rev/3b688d6ff3d0
22-03-2012

EVALUATION http://hg.openjdk.java.net/jdk8/tl/jdk/rev/0194fe5ca404
04-01-2012

EVALUATION http://hg.openjdk.java.net/hsx/hotspot-emb/hotspot/rev/3b688d6ff3d0
20-12-2011

SUGGESTED FIX Overview The diagnostic command framework is fully implemented in native code and relies on the HotSpot's internal exception mechanism. The rational of a pure native implementation is to be able to execute diagnostic commands even in critical situations like an OutOfMemory error. All diagnostic commands are registered in a single list, and two flags control the way a user can interact with them. The "hidden" flag prevents a diagnostic command from appearing in the list of available commands returned by the "help" command. However, it's still possible to get the detailed help message for a hidden command with the "help <command name>" syntax (but it requires to know the name of the hidden command). The second flag is "enabled" and it controls if a command can be invoked or not. When listed with the "help" commands, disabled commands appear with a "[disabled]" label in their description. If the user tries to invoke a disabled command, an error message is returned and the command is not run. This error message can be customized on a per command base. The framework just provides these two flags with their semantic, it doesn't provide any policy or mechanism to set or modify these flags. These actions will be delegated to the JVM or special diagnostic commands. DCmdParser framework The DCmdParser class is an optional framework to help development of argument parsers. It provides many features required by the diagnostic command framework (generation of the help message or the argument descriptions for the JMX interface) but all these features can easily be re-implemented if a developer decides not to use the DCmdParser framework. The DCmdParser class is relying on the DCmdArgument template. This template must be used to define the different types of argument the parser will have to handle. When a new specialization of the template is done, three methods have to be provided: void parse_value(const char *str,size_t len,TRAPS); void init_value(TRAPS); void destroy_value(); The parse_value() method is used to convert a string into an argument value. The print_value() method is used to display the default value (support for the detailed help message). The init_value() method is used to initialize or reset the argument value. The destroy_value() method is a clean-up method (useful when the argument has allocated some C-Heap memory to store its value and this memory has to be freed before destroying the DCmdArgument instance). The DCmdParser makes a distinction between options and arguments. Options are identified by a key name that must appear on the command line, while argument are identified just by the position of the argument on the command line. Options use the <key>=<value> syntax. In case of boolean options, the '=<value>' part of the syntax can be omitted to set the option to true. Arguments are just sequences characters delimited by a separator character. This separator can be specified at runtime when invoking the diagnostic command framework. If an argument contain a character that could be used as a delimiter, it's possible to enclose the argument between single or double quotes. Options are arguments are instantiated using the same DCmdArgument class but they're registered differently to the DCmdParser. The JCmd interface Diagnostic commands can also be invoked from outside the JVM process, using the new 'jcmd' utility. The jcmd program uses the attach API to connect to the JVM, send requests and receive results. The jcmd utility must be launched on the same machine than the one running the JVM (its a local tool). Launched without arguments, jcmd displays a list of all JVMs running on the machine. The jcmd source code is in the jdk repository like other existing j* tools. To execute a diagnostic command in a particular JVM, the generic syntax is: jcmd <pid_of_the_jvm> <command_name> [arguments] The attachListener has been modified to recognized the jcmd requests. When a jcmd request is identified, it is parsed to extract the command name. The JVM performs a look up of this command in a list of registered commands. To be executable by an external request, a diagnostic command has to be registered. The registration is performed with the DCmdFactory class (see services/management.cpp). The JMX interface The framework provides a JMX based interface to the diagnostic commands. This interface allows remote invocation of diagnostic commands through a JMX connection. The information related to the diagnostic commands are accessible through new methods added to the com.sun.management.HotspotDiagnosticMXBean: public List<String> getDiagnosticCommands(); public DiagnosticCommandInfo getDiagnosticCommandInfo(String command); public List<DiagnosticCommandInfo> getDiagnosticCommandInfo(List<String> command); public List<DiagnosticCommandInfo> getDiagnosticCommandInfo(); public String execute(String commandLine) throws IllegalArgumentException ; public String execute(String cmd, String... arguments) throws IllegalArgumentException; If the DiagnosticCommandArgumentInfo instance describes an option, isOption() returns true and getPosition() returns -1. Otherwise, when the DiagnosticCommandArgumentInfo instance describes an argument, isOption() returns false and getPosition() returns the expected position for this argument. The position of an argument is defined relatively to all arguments passed on the command line, options are not considered when defining an argument position. The getDefault() method returns the default value of the argument if a default has been defined, otherwise it returns null. The Diagnostic Commands To avoid name collisions between diagnostic commands coming from different projects, use of a flat name space should be avoided and a more structured organization is recommended. The framework itself doesn't depend on this organization, so it will be a set of rules defining a convention in the way commands are named. Diagnostic commands can easily organized in a hierarchical way, so the template for a command name can be: <domain>.[sub-domain.]<command> This template can be extended with sub-sub-domains and so on. A special set of commands without domain will be reserved for the commands related to the diagnostic framework itself, like the "help" command.
15-12-2011

EVALUATION http://hg.openjdk.java.net/hsx/hotspot-rt/hotspot/rev/3b688d6ff3d0
14-12-2011