openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jrba...@apache.org
Subject svn commit: r989324 - in /openjpa/trunk/openjpa-project/src/doc/manual: manual.xml ref_guide_conf.xml ref_guide_instrumentation.xml
Date Wed, 25 Aug 2010 19:48:01 GMT
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>
+            &lt;!--  Enable caches and cache statistics --&gt;
+            &lt;property name="openjpa.DataCache" value="true(EnableStatistics=true)"/&gt;
+            &lt;property name="openjpa.QueryCache" value="true(EnableStatistics=true)"/&gt;
+            &lt;property name="openjpa.jdbc.QuerySQLCache" value="true(EnableStatistics=true)"/&gt;
+            &lt;property name="openjpa.RemoteCommitProvider" value="sjvm"/&gt;
+
+            &lt;!--  Enable jmx provider and instruments for Data, Query, and QuerySQL
caches --&gt;
+            &lt;property name="openjpa.Instrumentation" value="jmx(Instrument='DataCache,QueryCache,QuerySQLCache')"/&gt;
+        </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=&lt;port&gt;.
+            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>
+            &lt;!--  Enable custom provider and instrument --&gt;
+            &lt;property name="openjpa.Instrumentation" value="com.my.app.InstrumentationProvider(Instrument='MySQLInstrument')"/&gt;
+        </programlisting>
+    </section>
+</chapter>

Propchange: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_instrumentation.xml
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message