<html><head> | |
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | |
<title>Chapter 16. Instrumentation</title><link rel="stylesheet" href="css/docbook.css" type="text/css"><base href="display"><meta name="generator" content="DocBook XSL Stylesheets V1.72.0"><link rel="start" href="manual.html" title="Apache OpenJPA 2.1 User's Guide"><link rel="up" href="ref_guide.html" title="Part 3. Reference Guide"><link rel="prev" href="ref_guide_optimization.html" title="Chapter 15. Optimization Guidelines"><link rel="next" href="ref_guide_instrumentation_custom.html" title="2. Custom Providers and Instruments"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 16. | |
Instrumentation | |
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_optimization.html">Prev</a> </td><th width="60%" align="center">Part 3. Reference Guide</th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_instrumentation_custom.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en" id="ref_guide_instrumentation"><div class="titlepage"><div><div><h2 class="title"><a name="ref_guide_instrumentation"></a>Chapter 16. | |
Instrumentation | |
</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="ref_guide_instrumentation.html#ref_guide_instrumentation_config">1. | |
Configuration | |
</a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_instrumentation.html#ref_guide_instrumentation_config_jmx">1.1. | |
JMX Platform MBean Enablement | |
</a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_instrumentation_custom.html">2. | |
Custom Providers and Instruments | |
</a></span></dt></dl></div><a class="indexterm" name="d0e36657"></a><p> | |
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 | |
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://download-llnw.oracle.com/javase/1.5.0/docs/tooldocs/share/jconsole.html" target="_top"> | |
<code class="classname">JConsole</code></a> can be used to monitor various | |
metrics tracked by OpenJPA's caches by accessing MBeans registered under domain | |
<code class="classname">org.apache.openjpa</code>. Additionally, custom applications can gather metrics by using the | |
JMX API to query OpenJPA's MBeans. The <code class="classname">openjpa-integration-jmx</code> | |
integration module contains an example of how to access the cache MBeans within program code. | |
</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_instrumentation_config"></a>1. | |
Configuration | |
</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_instrumentation.html#ref_guide_instrumentation_config_jmx">1.1. | |
JMX Platform MBean Enablement | |
</a></span></dt></dl></div><a class="indexterm" name="d0e36676"></a><p> | |
Instrumentation is enabled using the <a href="ref_guide_conf_openjpa.html#openjpa.Instrumentation" title="5.39. openjpa.Instrumentation"><code class="literal">openjpa.Instrumentation</code> </a> | |
configuration property. The base value is the instrumentation provider. The | |
alias "jmx" enables the JMX Platform MBean provider. Instruments are specified | |
on the <code class="literal">Instrument</code> 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: | |
</p><pre class="programlisting"> | |
<!-- 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')"/> | |
</pre><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_instrumentation_config_jmx"></a>1.1. | |
JMX Platform MBean Enablement | |
</h3></div></div></div><a class="indexterm" name="d0e36694"></a><p> | |
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: | |
</p><pre class="programlisting"> | |
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 | |
</pre><p> | |
</p><p> | |
Additional information regarding the use and configuration of JMX Platform MBeans | |
can be found in the | |
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://download.oracle.com/javase/6/docs/technotes/guides/jmx/overview/JMXoverviewTOC.html" target="_top"> | |
<code class="literal">Java Management Extensions (JMX) Technology Overview</code></a>. | |
</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_optimization.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_instrumentation_custom.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 15. | |
Optimization Guidelines | |
</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 2. | |
Custom Providers and Instruments | |
</td></tr></table></div></body></html> |