Author: jrbauer
Date: Wed Aug 25 19:48:01 2010
New Revision: 989324
URL: http://svn.apache.org/viewvc?rev=989324&view=rev
Log:
OPENJPA-1739 Documentation for instrumentation plugin
Added:
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_instrumentation.xml
(with props)
Modified:
openjpa/trunk/openjpa-project/src/doc/manual/manual.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml
Modified: openjpa/trunk/openjpa-project/src/doc/manual/manual.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/manual.xml?rev=989324&r1=989323&r2=989324&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/manual.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/manual.xml Wed Aug 25 19:48:01
2010
@@ -53,6 +53,7 @@
<!ENTITY ref_guide_slice.xml SYSTEM "ref_guide_slice.xml">
<!ENTITY ref_guide_integration.xml SYSTEM "ref_guide_integration.xml">
<!ENTITY ref_guide_optimization.xml SYSTEM "ref_guide_optimization.xml">
+ <!ENTITY ref_guide_instrumentation.xml SYSTEM
"ref_guide_instrumentation.xml">
<!ENTITY samples_guide.xml SYSTEM "samples_guide.xml">
<!ENTITY jpa_resources.xml SYSTEM "jpa_resources.xml">
<!ENTITY supported_databases.xml SYSTEM "supported_databases.xml">
@@ -113,6 +114,7 @@
&ref_guide_slice.xml;
&ref_guide_integration.xml;
&ref_guide_optimization.xml;
+ &ref_guide_instrumentation.xml;
</part>
<!--
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml?rev=989324&r1=989323&r2=989324&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml Wed Aug 25
19:48:01 2010
@@ -2124,7 +2124,50 @@ when the application refers to a resourc
</para>
</section>
-
+ <section id="openjpa.Instrumentation">
+ <title>
+ openjpa.Instrumentation
+ </title>
+ <indexterm zone="openjpa.Instrumentation">
+ <primary>
+ Instrumentation
+ </primary>
+ </indexterm>
+ <indexterm zone="Instrumentation">
+ <primary>
+ Instrumentation
+ </primary>
+ </indexterm>
+ <para>
+<emphasis role="bold">Property name: </emphasis><literal>
+openjpa.Instrumentation</literal>
+ </para>
+ <para>
+<emphasis role="bold">Configuration API:</emphasis>
+<ulink
url="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getInstrumentation()">
+<methodname>
+org.apache.openjpa.conf.OpenJPAConfiguration.getInstrumentation
+</methodname></ulink>
+ </para>
+ <para>
+<emphasis role="bold">Resource adaptor config-property: </emphasis><literal>
+Instrumentation</literal>
+ </para>
+ <para>
+<emphasis role="bold">Default: </emphasis><literal>-</literal>
+ </para>
+ <para>
+<emphasis role="bold">Possible values: </emphasis><literal>jmx</literal>,
+<literal>custom plugin string</literal>
+ </para>
+ <para>
+<emphasis role="bold">Description:</emphasis> A plugin string (see
+<xref linkend="ref_guide_conf_plugins"/>) describing one or more instances of
+<ulink
url="../javadoc/org/apache/openjpa/lib/instrumentation/InstrumentationProvider.html">
+<classname>org.apache.openjpa.lib.instrumentation.InstrumentationProvider</classname></ulink>
and
+specific instruments to enable. See <xref
linkend="ref_guide_instrumentation"/> for details.
+ </para>
+ </section>
<section id="openjpa.InverseManager">
<title>
Added:
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_instrumentation.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_instrumentation.xml?rev=989324&view=auto
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_instrumentation.xml
(added)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_instrumentation.xml
Wed Aug 25 19:48:01 2010
@@ -0,0 +1,155 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<chapter id="ref_guide_instrumentation">
+ <title>
+ Instrumentation
+ </title>
+ <indexterm zone="ref_guide_instrumentation">
+ <primary>
+ instrumentation
+ </primary>
+ </indexterm>
+ <para>
+ 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
+ <ulink
url="http://download-llnw.oracle.com/javase/1.5.0/docs/tooldocs/share/jconsole.html";>
+ <classname>JConsole</classname></ulink> can be used to monitor various
+ metrics tracked by OpenJPA's caches by accessing MBeans registered under
domain
+ <classname>org.apache.openjpa</classname>. Additionally, custom
applications can gather metrics by using the
+ JMX API to query OpenJPA's MBeans. The
<classname>openjpa-integration-jmx</classname>
+ integration module contains an example of how to access the cache MBeans
within program code.
+ </para>
+ <section id="ref_guide_instrumentation_config">
+ <title>
+ Configuration
+ </title>
+ <indexterm zone="ref_guide_instrumentation_config">
+ <primary>
+ configuration
+ </primary>
+ </indexterm>
+ <para>
+ Instrumentation is enabled using the <link
linkend="openjpa.Instrumentation"><literal>openjpa.Instrumentation</literal>
</link>
+ configuration property. The base value is the instrumentation
provider. The
+ alias "jmx" enables the JMX Platform MBean provider. Instruments are
specified
+ on the <literal>Instrument</literal> 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:
+ </para>
+ <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')"/>
+ </programlisting>
+ <section id="ref_guide_instrumentation_config_jmx">
+ <title>
+ JMX Platform MBean Enablement
+ </title>
+ <indexterm zone="ref_guide_instrumentation_config">
+ <primary>
+ configuration
+ </primary>
+ <secondary>
+ jmx
+ </secondary>
+ </indexterm>
+ <para>
+ 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:
+ <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
+ </programlisting>
+ </para>
+ <para>
+ Additional information regarding the use and configuration of JMX
Platform MBeans
+ can be found in the
+ <ulink
url="http://download.oracle.com/javase/6/docs/technotes/guides/jmx/overview/JMXoverviewTOC.html";>
+ <literal>Java Management Extensions (JMX) Technology
Overview</literal></ulink>.
+ </para>
+ </section>
+ </section>
+ <section id="ref_guide_instrumentation_custom">
+ <title>
+ Custom Providers and Instruments
+ </title>
+ <indexterm zone="ref_guide_instrumentation_custom">
+ <primary>
+ configuration
+ </primary>
+ </indexterm>
+ <para>
+ OpenJPA includes built-in support for a JMX Platform MBean provider,
but a custom instrumentation
+ providers can be created by implementing the
+ <ulink
url="../javadoc/org/apache/openjpa/lib/instrumentation/InstrumentationProvider.html">
+ <classname>InstrumentationProvider</classname></ulink> interface or
more simply by extending
+ <ulink
url="../javadoc/org/apache/openjpa/lib/instrumentation/AbstractInstrumentationProvider.html">
+ <classname>AbstractInstrumentationProvider</classname></ulink>. To
use the custom instrumentation provider,
+ include the class in your classpath and specify the class name as the
base value on the
+ <link
linkend="openjpa.Instrumentation"><literal>openjpa.Instrumentation</literal></link>
configuration property.
+ </para>
+ <para>
+ OpenJPA includes instruments for various caches, but you can also
create your own instruments. To
+ create a custom instrument you need to implement the
+ <ulink
url="../javadoc/org/apache/openjpa/lib/instrumentation/Instrument.html">
+ <classname>Instrument</classname></ulink> interface or more simply
extend
+ <ulink
url="../javadoc/org/apache/openjpa/lib/instrumentation/AbstractInstrument.html">
+ <classname>AbstractInstrument</classname></ulink>. If you are
building a Platform MBean JMX-based
+ instrument this effort can be simplified by extending
+ <ulink
url="../javadoc/org/apache/openjpa/instrumentation/jmx/JMXInstrument.html">
+ <classname>JMXInstrument</classname></ulink>. If you create your own
custom
+ provider, class name aliases can be registered within the provider to
simplify configuration. For example,
+ the instrument <classname>com.my.app.MySQLInstrument</classname> could
be aliased as
+ <classname>MySQLInstrument</classname> within custom provider
+ <classname>com.my.app.InstrumentationProvider</classname>.
+ </para>
+ <para>
+ OpenJPA provides the ability to plug in custom instruments and gives
instruments direct access to the
+ configuration, but it is up to the creator of the instrument to add
the internal monitoring. This often
+ requires modifying or extending base OpenJPA classes (such as the
Broker) or using a byte-code weaving
+ tool such as AspectJ to produce aspect-based instruments.
+ </para>
+ <para>
+ Here is an example of how a custom instrumentation provider could be
enabled with an instrument class
+ aliased by the provider as <classname>MySQLInstrument</classname>.
+ </para>
+ <programlisting>
+ <!-- Enable custom provider and instrument -->
+ <property name="openjpa.Instrumentation"
value="com.my.app.InstrumentationProvider(Instrument='MySQLInstrument')"/>
+ </programlisting>
+ </section>
+</chapter>
Propchange:
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_instrumentation.xml
------------------------------------------------------------------------------
svn:eol-style = native
