openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
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

OPENJPA-1739 Documentation for instrumentation plugin

    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/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_instrumentation.xml;

Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml
--- 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
+        <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>
+            </para>
+            <para>
+<emphasis role="bold">Configuration API:</emphasis>
+<ulink url="../javadoc/org/apache/openjpa/conf/OpenJPAConfiguration.html#getInstrumentation()">
+            </para>
+            <para>
+<emphasis role="bold">Resource adaptor config-property: </emphasis><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">
+specific instruments to enable. See <xref linkend="ref_guide_instrumentation"/> for
+            </para>
+        </section>
         <section id="openjpa.InverseManager">

Added: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_instrumentation.xml
--- 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
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ 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="">

+    <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
+    </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>
+        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,
+            monitoring of your application, specify the
+   directives on the java command line
invocation.  To enable
+            remote instrumentation on a specific port, specify which port to use on the directive

+  ;port&gt;.
+            For example:
+            <programlisting>
+            java -cp openjpa-all-2.1.0.jar:myApplication.jar
+            </programlisting>
+            </para>
+            <para>
+            Additional information regarding the use and configuration of JMX Platform MBeans
+            can be found in the 
+            <ulink url="">
+            <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
+        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
+        <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></classname> could
be aliased as 
+        <classname>MySQLInstrument</classname> within custom provider 
+        <classname></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="'MySQLInstrument')"/&gt;
+        </programlisting>
+    </section>

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

View raw message