You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by cw...@apache.org on 2009/08/11 22:11:28 UTC
svn commit: r803274 - in
/incubator/uima/uima-as/trunk/uima-as-docbooks/src/docbook/uima_async_scaleout:
async.overview.xml ref.async.api.xml ref.async.deployment.xml
Author: cwiklik
Date: Tue Aug 11 20:11:27 2009
New Revision: 803274
URL: http://svn.apache.org/viewvc?rev=803274&view=rev
Log:
UIMA-1484 Updated to include recent changes: changed client listener API, added JMX monitor description, added descriptions for new attributes in the deployment descriptor
Modified:
incubator/uima/uima-as/trunk/uima-as-docbooks/src/docbook/uima_async_scaleout/async.overview.xml
incubator/uima/uima-as/trunk/uima-as-docbooks/src/docbook/uima_async_scaleout/ref.async.api.xml
incubator/uima/uima-as/trunk/uima-as-docbooks/src/docbook/uima_async_scaleout/ref.async.deployment.xml
Modified: incubator/uima/uima-as/trunk/uima-as-docbooks/src/docbook/uima_async_scaleout/async.overview.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uima-as/trunk/uima-as-docbooks/src/docbook/uima_async_scaleout/async.overview.xml?rev=803274&r1=803273&r2=803274&view=diff
==============================================================================
--- incubator/uima/uima-as/trunk/uima-as-docbooks/src/docbook/uima_async_scaleout/async.overview.xml (original)
+++ incubator/uima/uima-as/trunk/uima-as-docbooks/src/docbook/uima_async_scaleout/async.overview.xml Tue Aug 11 20:11:27 2009
@@ -921,6 +921,91 @@
results. Later versions may include additional UIMA-specific tooling for this.</para>
<section id="ugr.async.ov.concepts.mc.what">
<title>Instrumentation provided</title>
+ <para>UIMA AS Service has a built-in, JMX-based instrumentation that enables service monitoring. It
+ provides service metrics collected in real-time at configurable checkpoint intervals. The main purpose
+ of the monitor is to help in detecting overloaded and idle services. Overloaded services are those
+ that are not able to keep up with the work load. Idle services are those that are not receiving enough
+ work and stay idle. To detect both conditions, the monitor provides the following metrics: </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Input queue depth: number of CASes waiting to be processed by a service</para>
+ </listitem>
+ <listitem>
+ <para>Reply queue depth: number of CASes processed by a service and delivered to a client's queue</para>
+ </listitem>
+ <listitem>
+ <para>Number of CASes processed since the last checkpoint</para>
+ </listitem>
+ <listitem>
+ <para>Idle time since the last checkpoint</para>
+ </listitem>
+ <listitem>
+ <para>Time spent in analysis since the last checkpoint</para>
+ </listitem>
+ <listitem>
+ <para>Cas Pool size</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In addition to the performance metrics the monitor also provides basic service information:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Service name</para>
+ </listitem>
+ <listitem>
+ <para>Is service top level</para>
+ </listitem>
+ <listitem>
+ <para>Is service remote</para>
+ </listitem>
+ <listitem>
+ <para>Is service a cas multiplier</para>
+ </listitem>
+ <listitem>
+ <para>Number of processing threads</para>
+ </listitem>
+ <listitem>
+ <para>Service uptime</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The main metric for detecting an overloaded service is the input queue depth. If it is growing or high, the service
+ is not able to keep up with the load. There are more CASes arriving at the queue than the service can process.
+ Consider increasing number of processig threads in the JVm or start another instance of the service.</para>
+
+ <para>The main metric for detecting idle service is the idle time. If it is high, it indicates that the service is not
+ receiving enough CASes. This can be caused by a bottleneck in the service's client which can also be supported by
+ high reply queue depth. Ideally, the idle time should be at zero, which means that the service receives enough CASes
+ to process. The idle time is shown as a delta from the last time the checkpoint was made.</para>
+
+ <para>Cas Pool size at zero indicates misconfiguration or a bottleneck in a service's client. It should also be supported
+ by a high idle time. In this case, the service does not have enough CASes in its pool (misconfiguration) and is
+ forced to wait. A typical reason is a slow client which should be supported by a high reply queue depth. Consider
+ incrementing service's Cas pool and check the client's metrics to determine a reason why it is slow.</para>
+
+ <para>The monitor provides an API to plug in a custom formatter for displaying service metrics. A default implementation
+ is provided in the UIMA AS runtime. A custom formatter must implement JmxMonitorListener interface and can be
+ plugged in to the monitor with the following API:
+ <programlisting><![CDATA[ jmxMonitor.addJmxMonitorListener(customJmxListener);]]></programlisting></para>
+
+
+
+ <para>To easiest way to start a service with JMX monitoring enabled is to configure UIMA's property: UIMA_JVM_OPTS:</para>
+
+ <programlisting>
+ <![CDATA[set UIMA_JVM_OPTS=-Dcom.sun.management.jmxremote
+ -Dcom.sun.management.jmxremote.port=8009
+ -Dcom.sun.management.jmxremote.authenticate=false
+ -Dcom.sun.management.jmxremote.ssl=false
+ -Djmx.monitor.frequency=1000
+ -Djmx.monitor.formatter=<custom formatter class>]]></programlisting>
+
+ <para>The above configures JMX MBeanServer to run on port 8009 with no authentication. It also sets the checkpoint interval
+ to 1 second and plugs in a custom formatter for displaying metrics. Please note that the default formatter logs the metrics in
+ UIMA Log at INFO level.</para>
+
+ <!--
<para>The implementation provides the following kinds of instrumentation via JMX:
<itemizedlist>
<listitem>
@@ -940,7 +1025,18 @@
<para>by component</para></listitem>
<listitem>
<para>state: OK, Idle, Working, Stopped, restarting, etc.</para></listitem></itemizedlist>
- </listitem></itemizedlist> </para></section>
+ </listitem>
+ <listitem>
+ <para>lifecycle</para>
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>completeProcessingAndStop - finishes processing of in-play CASes and stops</para></listitem>
+ <listitem>
+ <para>stopNow - releases all CASes and stops</para></listitem></itemizedlist>
+ </listitem>
+ </itemizedlist> </para>
+ -->
+ </section>
<!-- of ugr.async.ov.concepts.mc.what --></section>
<!-- of ugr.async.ov.concepts.mc -->
<!-- ======================================================= -->
@@ -962,6 +1058,10 @@
value="tcp://uima17.watson.ibm.com:61616"/>
<parameter name="endpoint"
value="uima.as.RoomDateMeetingDetectorAggregateQueue"/>
+ <parameter name="timeout"
+ value="xxx"/>
+ <parameter name="getmetatimeout"
+ value="yyy"/>
</parameters>
</customResourceSpecifier>]]></programlisting>
Modified: incubator/uima/uima-as/trunk/uima-as-docbooks/src/docbook/uima_async_scaleout/ref.async.api.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uima-as/trunk/uima-as-docbooks/src/docbook/uima_async_scaleout/ref.async.api.xml?rev=803274&r1=803273&r2=803274&view=diff
==============================================================================
--- incubator/uima/uima-as/trunk/uima-as-docbooks/src/docbook/uima_async_scaleout/ref.async.api.xml (original)
+++ incubator/uima/uima-as/trunk/uima-as-docbooks/src/docbook/uima_async_scaleout/ref.async.api.xml Tue Aug 11 20:11:27 2009
@@ -227,6 +227,10 @@
<para>CpcTimeout: Collection process complete timeout. Default = no timeout.</para>
</listitem>
+ <listitem>
+ <para>SerializationStrategy:(Optional) xmi or binary serialization. Default = xmi </para>
+ </listitem>
+
</itemizedlist></para>
</section>
@@ -238,27 +242,39 @@
<section id="ugr.ref.async.callback.listener">
<title>Status Callback Listener</title>
<para>Asynchronous events are delivered to applications via methods in classes registered
- to the API object with addStatusCallbackListener(). These classes must implement the
- interface org.apache.uima.aae.client.UimaASStatusCallbackListener.
+ to the API object with addStatusCallbackListener(). These classes must extend the
+ class org.apache.uima.aae.client.UimaAsBaseCallbackListener.
+ <!-- These classes must implement the
+ interface org.apache.uima.aae.client.UimaASStatusCallbackListener.-->
<itemizedlist>
<listitem>
- <para>initializationComplete(EntityProcessStatus aStatus): The callback used to inform the
+ <para>initializationComplete(UimaASProcessStatus aStatus): The callback used to inform the
application that the initialization request has completed. On success aStatus will be
- null; on failure use the EntityProcessStatus class to get the details.</para>
+ null; on failure use the UimaASProcessStatus class to get the details.</para>
</listitem>
<listitem>
- <para>entityProcessComplete(CAS aCas, EntityProcessStatus aStatus): The callback used to
- inform the application that a processCas request has completed. On success aStatus
- will be null; on failure use the EntityProcessStatus class to get the details.</para>
+ <para>entityProcessComplete(CAS aCas, UimaASProcessStatus aStatus): The callback used to
+ inform the application that a processCas request has completed. On success aCAS object
+ will contain result of analysis; on failure the CAS will be in the same state as
+ before it was sent to a service. The aStatus object will contain a unique CAS id
+ that can be retrieved with getCasReferenceId() method; on failure use the
+ UimaASProcessStatus class to get the details.</para>
</listitem>
<listitem>
- <para>collectionProcessComplete(EntityProcessStatus aStatus): The callback used to inform the
+ <para>collectionProcessComplete(UimaASProcessStatus aStatus): The callback used to inform the
application that the CPC request has completed. On success aStatus will be
- null; on failure use the EntityProcessStatus class to get the details.</para>
+ null; on failure use the UimaASProcessStatus class to get the details.</para>
+ </listitem>
+
+ <listitem>
+ <para>onBeforeMessageSend(UimaASProcessStatus status): The callback used to inform the
+ application that a CAS is about to be sent to a service. The status object has
+ getCasReferenceId() method that returns a unique CAS id assigned by Uima AS.</para>
</listitem>
+
</itemizedlist>
</para>
</section>
@@ -380,6 +396,24 @@
</section>
</section>
+
+ <section id="ugr.ref.async.api.usage_undeployservice">
+ <title>Undeploying a Service with the Client API</title>
+ <para>
+ Services can be undeployed from a client object as follows:
+ <programlisting>// create Map to hold required parameters
+Map<String,Object> appCtx = new HashMap<String,Object>();
+appCtx.put(UimaAsynchronousEngine.DD2SpringXsltFilePath,
+ System.getenv("UIMA_HOME") + "/bin/dd2spring.xsl");
+appCtx.put(UimaAsynchronousEngine.SaxonClasspath,
+ "file:" + System.getenv("UIMA_HOME") + "/saxon/saxon8.jar");
+String id = uimaAsEngine.deploy(service, appCtx);
+uimaAsEngine.undeploy(id);
+ </programlisting>
+ </para>
+ </section>
+
+
<!--======================================================-->
<!-- Sample Code -->
<!--======================================================-->
@@ -390,4 +424,6 @@
</para>
</section>
+
+
</chapter>
Modified: incubator/uima/uima-as/trunk/uima-as-docbooks/src/docbook/uima_async_scaleout/ref.async.deployment.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uima-as/trunk/uima-as-docbooks/src/docbook/uima_async_scaleout/ref.async.deployment.xml?rev=803274&r1=803273&r2=803274&view=diff
==============================================================================
--- incubator/uima/uima-as/trunk/uima-as-docbooks/src/docbook/uima_async_scaleout/ref.async.deployment.xml (original)
+++ incubator/uima/uima-as/trunk/uima-as-docbooks/src/docbook/uima_async_scaleout/ref.async.deployment.xml Tue Aug 11 20:11:27 2009
@@ -89,8 +89,8 @@
<environmentVariables .../> <!--optional -->
<analysisEngine key="key name" async="[true/false]"
- internalReplyQueueScaleout="nn1"
- inputQueueScaleout="nn2">
+ internalReplyQueueScaleout="nn1" <!-- optional -->
+ inputQueueScaleout="nn2"> <!-- optional -->
<scaleout numberOfInstances="1"/> <!-- optional -->
<!-- optional -->
@@ -107,7 +107,7 @@
</analysisEngine>
. . .
<remoteAnalysisEngine key="key name" <!-- 0 or more -->
- remoteReplyQueueScaleout="nn1">
+ remoteReplyQueueScaleout="nn1"> <!-- optional -->
<!-- next is either required or must be omitted -->
<casMultiplier poolSize="5" initialFsHeapSize="nnn"/>
@@ -217,7 +217,10 @@
endpoint="queue_name"
prefetch="1"/>]]></programlisting>
- <para>The queue broker address includes a protocol specification, which should be set to either "tcp", or
+ <para>
+ The brokerURL attribute is optional. When omitted, a default value of tcp://localhost:61616 will be used.
+ A different brokerURL can be provided as an override when launching a service. Consult README that provides
+ an example of brokerURL override. The queue broker address includes a protocol specification, which should be set to either "tcp", or
"http". <!-- for brokers running on other JVMs, and "vm" for brokers running in the
same JVM.<! - having queue connections only to endpoints in this same JVM.- > For the "tcp", "http"
protocols, t-->The brokerURL attribute specifies the queue broker URL, typically its network address and
@@ -338,8 +341,8 @@
<programlisting><![CDATA[<analysisEngine key="key name" async="true"
- internalReplyQueueScaleout="nn1"
- inputQueueScaleout="nn2">
+ internalReplyQueueScaleout="nn1" <!-- optional -->
+ inputQueueScaleout="nn2"> <!-- optional -->
<scaleout numberOfInstances="1"/> <!-- optional -->
<!-- casMultiplier is either required, or must be omitted-->
@@ -355,12 +358,12 @@
</analysisEngine>
. . .
<remoteAnalysisEngine key="key name" <!-- 0 or more -->
- remoteReplyQueueScaleout="nn1">
+ remoteReplyQueueScaleout="nn1"> <!-- optional -->
<!-- next is either required or must be omitted -->
<casMultiplier poolSize="5" initialFsHeapSize="nnn"/>
<inputQueue ... />
- <serializer method="xmi"/> <!-- optional -->
+ <serializer method="[xmi|binary]"/> <!-- optional -->
<asyncAggregateErrorConfiguration .../> <!-- optional -->
</remoteAnalysisEngine>
. . .
@@ -435,10 +438,13 @@
has to be deserialized.
</para>
+ <para>The <serializer> element describes what method of serialization to use. This element is optional and it
+ may be set to either binary or xmi. If omitted, xmi serialization will be used by default. Xmi serialization
+ can be quite verbose and produce large output for CASes containing many annotations. A more efficient and compact
+ serialization is produced by binary serialization which trades output size for more CPU required.
+ </para>
<para>
- The <inputQueue> element specifies the remote's input queue. The <serializer>
- element describes what method of serialization to use (for now "xmi" is the only allowed value, and this element
- can be omitted). The casMultiplier element inside a remoteAnalysisEngine element is only specified if the
+ The <inputQueue> element specifies the remote's input queue. The casMultiplier element inside a remoteAnalysisEngine element is only specified if the
remote component is a CAS Multiplier, and it specifies the size of a pool of CASes kept to receive the new CASes
from the remote component, and the initial size of those CASes. Its poolSize must be equal to or larger than the
casMultiplier poolSize specified for that remote component.</para>