Knowledge Base

Notice Information in this article applies to Excelsior JET version 4.0 and above.

Update: Excelsior JET 11.3 and above partially support ThreadMXBean functionality, which enables JMX tools to retrieve the stacks of all threads.

SUMMARY

Being a compliant Java SE platform implementation, Excelsior JET in particular supports the Management API, the JMX (Java Management Extensions) technology, and SNMP. This means that you can monitor and manage your optimized applications using any JMX client such as JConsole, or an SNMP client such as Nagios. This article shows how to enable monitoring.

Note: There is a number of HotSpot-specific management and monitoring features in the reference implementation. They are not supported.

DETAILS

Local Monitoring Using JMX

Starting from version 6, HotSpot has local monitoring and management enabled out-of-the box. You simply fire up JConsole, VisualVM, or a JMX client of your choice and choose a Java process from the list.

Excelsior JET only supports remote monitoring and management. You can circumvent this restriction by enabling remote monitoring but limiting it to localhost.

Remote monitoring and management require security, so password authentication and SSL/TLS are enabled by default. You can disable them for local operation on your development system, but it is highly recommended to leave them in place on a production server!

To enable local connections to the JMX agent without authentication, set four system properties at application startup:

com.sun.management.jmxremote.port=port

port is the number of the port through which you want to enable JMX connections.

com.sun.management.jmxremote.authenticate=false

Disable authentication

com.sun.management.jmxremote.ssl=false

Disable SSL

java.rmi.server.hostname=127.0.0.1

Make the RMI objects available only if requested through the loopback interface

Examples

Windows .bat file launching a conventional executable:

SET JETVMPROP=-Dcom.sun.management.jmxremote.port=1234 ^
              -Dcom.sun.management.jmxremote.authenticate=false ^
              -Dcom.sun.management.jmxremote.ssl=false ^
              -Djava.rmi.server.hostname=127.0.0.1
MyApp.EXE

Linux, command line launching a multi-app executable:

./myapp -Dcom.sun.management.jmxremote.port=1234 \
        -Dcom.sun.management.jmxremote.authenticate=false \
        -Dcom.sun.management.jmxremote.ssl=false \
        -Djava.rmi.server.hostname=127.0.0.1 \
        MyMainClass

Linux, Tomcat startup script:

CATALINA_OPTS="-Dcom.sun.management.jmxremote.port=1234 \
               -Dcom.sun.management.jmxremote.authenticate=false \
               -Dcom.sun.management.jmxremote.ssl=false \
               -Djava.rmi.server.hostname=127.0.0.1"

Running JConsole on the same system:

jconsole localhost:1234

Remote Monitoring Using JMX or SNMP

Java Platform documentation [1] provides extensive information on configuring secure remote monitoring and management using JMX and SNMP. You will find the respective configuration and template files in the jre/lib/management subdirectory of the active Excelsior JET profile, for instance:

C:\jet11.3-ent\profile1.8.0_101\jre\lib\management

You can tweak the configuration files and create the password and access files right in that directory. JetPackII will automatically pick them up during packaging. If you also use the same copy of Excelsior JET to build applications that you do not plan to monitor, you may wish to create a separate profile first.

Troubleshooting

Remote JMX and RMI

One thing that the JMX chapter of the Monitoring and Management Guide [1] does not mention is that you may also need to configure RMI, on top of which JMX works. Specifically, if you cannot establish a remote connection, try setting the java.rmi.server.hostname property to the fully qualified domain name of the system, or to the IP address of the network interface to which you are connecting:

-Djava.rmi.server.hostname=hostname | ip-address

Servers running behind a NAT are particularly susceptible to this problem.

Java Runtime Slim-Down

If you are taking advantage of the Java Runtime Slim-Down technology and your application itself does not use the Management API, that API will be marked as safe to detach.

If you try to enable remote monitoring of an application that was deployed with the Management API detached and the runtime fails to download the detached package, the application will terminate with the following error:

Required system class sun/management/Agent not found

JET RUNTIME HAS DETECTED UNRECOVERABLE ERROR #44 (runtime trap).

This peculiarity can be (ab)used to disable monitoring of your application. But if you plan to monitor and manage your application, make sure to not detach the Management API.

REFERENCES

  1. Java SE Monitoring and Management Guide. http://docs.oracle.com/javase/6/docs/technotes/guides/management/toc.html
  2. Excelsior JET User’s Guide (https://www.excelsiorjet.com/docs), Chapter “Application Considerations”, section “Java System Properties”.

Article ID: 36
Last Revised On: 30-Aug-2016