Table of Contents
OpenJPA provides the ability to instrument various aspects of runtime
operation. Instrumentation involves an instrumentation provider for base instrumentation
capabilities and instruments for instrumenting various aspects of OpenJPA. OpenJPA
includes a default instrumentation provider for JMX Platform MBeans. MBean-based instruments
are provided for the data cache, query cache, and query SQL cache. When enabled,
JMX-based remote monitoring tools such as
JConsole can be used to monitor various
metrics tracked by OpenJPA's caches by accessing MBeans registered under domain
org.apache.openjpa. Additionally, custom applications can gather metrics by using the
JMX API to query OpenJPA's MBeans. The openjpa-integration-jmx
integration module contains an example of how to access the cache MBeans within program code.
Instrumentation is enabled using the openjpa.Instrumentation
configuration property. The base value is the instrumentation provider. The
alias "jmx" enables the JMX Platform MBean provider. Instruments are specified
on the Instrument attribute of the provider. Multiple instruments can be specified
by enclosing the value in single quotes and specifying each instrument or instrument
alias as a comma separated list. For example:
<!-- Enable caches and cache statistics -->
<property name="openjpa.DataCache" value="true(EnableStatistics=true)"/>
<property name="openjpa.QueryCache" value="true(EnableStatistics=true)"/>
<property name="openjpa.jdbc.QuerySQLCache" value="true(EnableStatistics=true)"/>
<!-- Enable jmx provider and instruments for Data, Query, and QuerySQL caches -->
<property name="openjpa.Instrumentation" value="jmx(Instrument='DataCache,QueryCache,QuerySQLCache')"/>
The built-in JMX Platform MBean provider can be used to monitor OpenJPA runtime information out-of-band. This provider is based upon the Platform MBean support included in the JDK. The JDK provides options for enabling secure connectivity and authentication. These options require additional configuration options and may require encryption keys to be installed on the local and remote systems. To enable simple, non-secure, non-authenticated monitoring of your application, specify the -Dcom.sun.management.jmxremote.authenticate=false and -Dcom.sun.management.jmxremote.ssl=false directives on the java command line invocation. To enable remote instrumentation on a specific port, specify which port to use on the directive -Dcom.sun.management.jmxremote.port=<port>. For example:
java -cp openjpa-all-2.2.0.jar:myApplication.jar -Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.port=8888 com.my.app.Main
Additional information regarding the use and configuration of JMX Platform MBeans
can be found in the
Java Management Extensions (JMX) Technology Overview.