Chapter 16.  Instrumentation

Table of Contents

1. Configuration
1.1. JMX Platform MBean Enablement
2. Custom Providers and Instruments

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.

1.  Configuration

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)"/>
            <property name="openjpa.RemoteCommitProvider" value="sjvm"/>

            <!--  Enable jmx provider and instruments for Data, Query, and QuerySQL caches -->
            <property name="openjpa.Instrumentation" value="jmx(Instrument='DataCache,QueryCache,QuerySQLCache')"/>
        

1.1.  JMX Platform MBean Enablement

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.1.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.