You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by ch...@apache.org on 2015/06/08 20:09:44 UTC
svn commit: r1684237 -
/uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/services.tex
Author: challngr
Date: Mon Jun 8 18:09:43 2015
New Revision: 1684237
URL: http://svn.apache.org/r1684237
Log:
UIMA-4109 Update docs for 2.0.0.
Modified:
uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/services.tex
Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/services.tex
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/services.tex?rev=1684237&r1=1684236&r2=1684237&view=diff
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/services.tex (original)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/services.tex Mon Jun 8 18:09:43 2015
@@ -30,7 +30,7 @@
Users may supply their own ``pingers'' by supplying a Java class that implements
the pinger API. This is referred to as a ``custom'' pinger in this document.
There are a number of service registration options which allow
- specification and parameterization of customn pingers.
+ specification and parametrization of custom pingers.
\end{itemize}
The pinger API enables the following functions for custom pingers:
@@ -40,7 +40,7 @@
\item enable and disable service autostart,
\item notify the Service Manager of the date of last use of a service,
\item notify the Service Manager of the health and availability of a service,
- \item returns a string for display in the DUCC Web server to show relevent service information
+ \item returns a string for display in the DUCC Web server to show relevant service information
\end{itemize}
@@ -59,14 +59,16 @@
\end{itemize}
When work enters the system with a declared dependency on a service, one of the following
- actions is tken:
+ actions is taken:
\begin{itemize}
- \item If the service is not registered, the work request is automatically canceled.
- \item If the service is not running, the Service Manager attempts to start it; the job
+ \item If the service is not registered, the work request is automatically canceled (to avoid
+ wasting resources on a job that is known cannot succeed.)
+ \item If the service registered but not running, the Service Manager attempts to start it; the job
remains queued until the service is started and its pinger reports good health.
- \item If the service exists but cannot be started, the work remains queued and error
+ \item If the service exists but cannot be started, the remains queued and error
status is shown in the web server. Once the service is working again the
- work is allowed to proceed.
+ work is allowed to proceed. (Jobs already running are not directly affected, unless they
+ also cannot access the service.)
\item If the service processes are running but the pinger reports failure contacting the service,
the work remains queued with error status shown in the webserver. Once the service
pinger indicates the service is functional again the work is allowed to proceed.
@@ -77,7 +79,7 @@
DUCC supports two types of services: UIMA-AS and CUSTOM:
\begin{description}
- \item[UIMA-AS] This is a "normal" UIMA-AS service. DUCC fully supports all aspects of UIMA-AS
+ \item[UIMA-AS] This is a normal UIMA-AS service. DUCC fully supports all aspects of UIMA-AS
services with minimal effort from developers. A default pinger is supplied by DUCC
for UIMA-AS services. It is legal to define a custom pinger for a UIMA-AS service.
@@ -86,9 +88,9 @@
\end{description}
DUCC also supports services that are not managed by DUCC. These are known as {\em ping-only}
- services. The registration for a ping-only service contains only keywords needed to
- support a pinger. Ping-only services must be defined as custom services; there is no
- default pinger provided for ping-only services.
+ services. The registration for a ping-only service contains only keywords needed to support a
+ pinger, which communicates with the non-DUCC service. Ping-only services must
+ be defined as custom services; there is no default pinger provided for ping-only services.
\section{Service Instance IDs}
\label{sec:service.service.ids}
@@ -96,7 +98,7 @@
started, the SM assigns monotonically increasing IDs to each service instance, starting
with ID 0, up the the maximum number of instances started.
- If an instance exits unexpectedly, the SM respawns it (unless a failure threshold has been
+ If an instance exits unexpectedly, the SM re-spawns it (unless a failure threshold has been
exceeded). The new instance is assigned the same instance ID as the instance it replaces.
This insures that, for example, instance ``three'' is always started as instance ``three'',
maintained constant over failures and SM restarts.
@@ -123,14 +125,14 @@
The {\em service-type} must be either UIMA-AS or CUSTOM.
The {\em unique id} is any string needed to ensure the service is
- uniquely named. For UIMA-AS services, the unique-id must be the same as the
+ uniquely named. For UIMA-AS services, the unique ID must be the same as the
service endpoint specified in service's DD XML descriptor. The UIMA-AS
service endpoint is always of the form:
\begin{verbatim}
- UIMA-AS:queue-name:broker-url
+ queue-name:broker-url
\end{verbatim}
where {\em queue-name} is the name of the ActiveMQ queue used by the service, and {\em broker-url}
- is the ActiveMQ broker URL. For example
+ is the ActiveMQ broker URL. Sample DUCC Service endpoints:
\begin{verbatim}
UIMA-AS:WikipediaSearchServices:tcp://broker1:61616
UIMA-AS:GoogleSearchServices:http://broker2:61618
@@ -154,15 +156,15 @@
system is first booted. If an instance should die, DUCC automatically restarts the
instance and continually maintains the registered number of service instances.
- To handle fatal errors in {\em autostarted} services, The Service Manager maintains a time
+ By default, to handle fatal errors in {\em autostarted} services, The Service Manager maintains a time
window in which only a specific number of instance failures may occur. If the number of
failures within that window of time is excessive DUCC will set a {\em disabled} flag and
no longer restart instances. Instance which do not fail are left running. The {\em
disabled} flag must be manually reset once the problem is resolved before new instances
can be started.
- The default failure policy is implemented in the service pingers. Service
- owners may redefine the policy by supplying their own pingers for a service.
+ The default failure policy is implemented in the service pinger.. Service
+ owners may redefine the default policy by supplying their own pingers for a service.
\item[Reference-started Services] A reference-started service is a registered service that
is started only when referenced by another job or service. If the service is already
@@ -170,7 +172,7 @@
not, the service registry is checked and if a matching enabled service is found, it is
started by DUCC. While the service is being started, jobs are held ``Waiting For Services''
to ensure the service is viable. Once the service has completed initialization and the pinger
- indicates it is viable, all work waiting on it are then marked ``Services Available'' and
+ indicates it is viable, all work waiting on it is then marked ``Services Available'' and
started.
To handle fatal errors in {\em reference-started} services, The Service Manager maintains
@@ -178,7 +180,7 @@
number of failures within that window of time is excessive DUCC will set a {\em disabled}
flag and no longer restart instances. Instance which do not fail are left running. The
{\em disabled} flag must be manually reset once the problem is resolved before new
- instances can be started.
+ instances can be started. This default policy may be overridden by custom pingers.
When the last job or service that references the on-demand service exits, a timer is
established to keep the service alive for a while, in anticipation that it will be needed
@@ -208,6 +210,7 @@
\end{description}
+ \paragraph{Dynamically Changing Service Policies}
A service may be {\em stopped}; that is, no instances are running. This state can occur
if the service has experienced too many errors within its failure window, in which case
the service is {\em disabled}, or because the service is not {\em autostarted} or {\em referenced} by
@@ -267,7 +270,7 @@
to the service.
\item Determine the health of the service by issuing a JMX call to the UIMA-AS broker
to collect queueing statistics.
- \item Manages the failure window of the service.
+ \item Manage the failure window of the service.
\item Returns a string with basic ActiveMQ statistics about the service, or
error information if the service is deemed unusable.
\item Returns date of last use of the service (as determined by presence or
@@ -275,7 +278,7 @@
\end{itemize}
Users may supply their own pingers. The following additional functions are available for
- pingers. Note that a ``custom'' pinger MAY be supplied for UIMA-AS services, and
+ pingers. Note that a {\em custom} pinger MAY be supplied for UIMA-AS services, and
MUST be supplied for CUSTOM services. Custom pingers use the Service Manager's
``pinger'' API to perform the following tasks:
\begin{itemize}
@@ -306,15 +309,15 @@
specific field names and types.
\subsubsection{Pinger Initialization Data}
- Data provided once, during pinger intialization, includes:
+ Data provided once, during pinger initialization, includes:
\begin{description}
\item[Arguments] This is the {\em service\_ping\_arguments} string from the
service registration.
- \item[Endpint] This is the CUSTOM:string or UIMA-AS:string endpoint provided
+ \item[Endpoint] This is the CUSTOM:string or UIMA-AS:string endpoint provided
in the service registration.
\item[Monitor Rate] This is the rate at which the pinger will be called by
the SM, as provided in DUCC's configuration.
- \item[Service ID] This is the unique numeric service ID assigned to the service
+ \item[Service ID] This is the \hyperref[sec:service.service.ids]{unique numeric service ID} assigned to the service
by DUCC.
\item[Log Enabled] Whether the service log is enabled, as specified by the
{\em service\_ping\_dolog} registration parameter.
@@ -322,7 +325,7 @@
parameter, provided by DUCC configuration and optionally overridden by the
service registration.
\item[Instance Failure Window] This is the value of the {\em instance\_failures\_window}
- prameter, provided by DUCC configuration and optionally overridden by the
+ parameter, provided by DUCC configuration and optionally overridden by the
service registration.
\item[Autostart Enabled] This indicates whether the service registration currently
has the {\em autostart} flag enabled.
@@ -333,14 +336,14 @@
\subsubsection{Pinger Dynamic Data}
- Information provided in each call (ping) consists of:
+ Dynamic information provided to the pinger in each call (ping) consists of:
\begin{description}
\item[All Instance Information] This is an array consisting of the unique integer
- IDS of all running proceses implementing the service. This includes instances
+ IDS of all running processes implementing the service. This includes instances
which may not be currently viable for some reason (still initializing, for example).
\item[Active Instance Information] This is an array consisting of the unique integer
- IDS of all running proceses implementing the service. This is a subset of
+ IDS of all running processes implementing the service. This is a subset of
``All Instance Information'' and includes only the service instances that are advanced
to Running state.
@@ -424,7 +427,7 @@ public class CustomPing
stats.setInfo( "S1[" + stat1 + "] S2[" + stat2 +
"] S3[" + stat3 + "] S4[" + stat4 + "]" );
} catch ( Throwable t) {
- t.printStackTrace();
+ t.printStackTrace();
stats.setInfo(t.getMessage());
}
return stats;
@@ -454,7 +457,7 @@ public class CustomPing
This will log any output from {\tt System.out.println()} to the declared log directory
for the service. If not specified in the reqistration, this directory is:
\begin{verbatim}
- $HOME/ducc/logs/<serviceid>/services
+ $HOME/ducc/logs/S-<serviceid>/services
\end{verbatim}
where {\tt$<$servicid$>$} is the DUCC-assigned ID of your service.
@@ -466,7 +469,7 @@ public class CustomPing
A sample service registration may look something like the following. Note that you do not need
to include any of the DUCC jars in the classpath for the pinger. DUCC will add the jars it
requires to interact with the pinger automatically. (However you may need other jars to
- provide UIMA, UIMA-AS, ActiveMQ, Spring, or other services.)
+ provide UIMA, UIMA-AS, ActiveMQ, Spring, or other function.)
\begin{verbatim}
bash-3.2$ cat myping.svc
@@ -480,15 +483,15 @@ public class CustomPing
service_ping_jvm_args = -DXmx50M
\end{verbatim}
- \paragraph{3. Register and start the pinger} Start up your custom service so the pinger has something to contact, then start
- the pinger. It may be easier to debug the pinger if you initially start the service outside of DUCC. Once
- the pinger is working it is straightforward to integrate it into the pinger's service registration by merging
- the registration for the pinger with the registration for the service.
-
- That's it! Check the web server to make sure the service ``comes alive''. Check your pinger's
- debugging log if it doesn't. Once registered, you can dynamically modify and restart the pinger at any time without
- reregistering the service or restarting the service by use of the {\tt $--$modify} option of the
- ducc\_services CLI:
+ \paragraph{3. Register and start the service and pinger} Start up your custom service so the pinger with
+ the registration containing lines similar to those above. As soon as the service instance is in
+ DUCC state {\em Running} the SM starts the pinger.
+
+
+ Check the web server to make sure the service ``comes alive''. Check your pinger's
+ debugging log if it doesn't. Once registered, you can dynamically modify and restart the pinger at any time without
+ re-registering the service or restarting the service by use of the {\tt $--$modify} option of the
+ \hyperref[sec:cli.ducc-services]{\em ducc\_services CLI:}
\begin{verbatim}
ducc_services --modify <serviceid> --service_ping_dolog true
ducc_services --modify <serviceid> --service_ping_class OtherCustsomPing
@@ -508,8 +511,8 @@ public class CustomPing
\subsection{Globally Registered Pingers}
\label{subsec:services.pingers}
- A pinger may be registered with DUCC so that it is available to all users of DUCC services. To do
- this, a registration file containing only pinger-specific parameters is created in DUCC's runtime
+ A user-built pinger may be registered with DUCC so that it can be globally used by any DUCC service. To do
+ this, a registration file containing only pinger-specific parameters is created in DUCC's run-time
directory. Such a pinger may then be designated for a service by using its registered filename
instead of its class in the {\em service\_ping\_class} field of a registration. There is no API or
CLI to register such a pinger; only a DUCC administrator may create a global ping registration.
@@ -522,13 +525,15 @@ public class CustomPing
A service may override any of the options of a globally-registered {\em external} pinger,
thus allowing significant reuse of existing code. Only the {\em service\_ping\_arguments}
- of an {\em internal} pinger may be overridden howver.
+ of an {\em internal} pinger may be overridden however.
The default UIMA-AS pinger is permanently registered as an {\em internal} pinger.
- Globally registered pingers use a special boolean property, not suppored by the
+ Globally registered pingers use a special boolean property, not supported by the
{\em ducc\_services} API/CLI, ``internal'', to determine whether the pinger is
- to be run internally to SM or as an external process.
+ to be run internally to SM or as an external process. Only the DUCC administrator
+ may update a global pinger's registration to ``internal'', to insure such pingers
+ are properly vetted and approved by the installation.
More Details of registering global pingers is found in the
\hyperref[chap:sm]{\em Administration section} of this document.
@@ -549,7 +554,7 @@ public class CustomPing
\subsection{Using the Sample Pinger}
The following arguments may be specified to use the sample pinger with any UIMA-AS service. The
- {\em service\_ping\_arguemnts} are specific to this pinger.
+ {\em service\_ping\_arguments} are specific to this pinger.
\begin{verbatim}
service_ping_class=org.apache.uima.ducc.ping.SamplePing
service_ping_arguments=meta-timeout=15010,broker-jmx-port=1099,window=5,min=1,
@@ -565,32 +570,13 @@ public class CustomPing
instance_failures_limit = ${ducc.sm.instance.failure.max}
\end{verbatim}
- The pinger may optionally registered as a ``global'' pinger with the Service Manager by placing
- one or both of the ping registrations by copying the two files
-\begin{verbatim}
- org.apache.uima.ducc.ping.SamplePing
- org.apache.uima.ducc.ping.SamplePing.external
-\end{verbatim}
- from
-\begin{verbatim}
- DUCC_HOME/examples/ping
-\end{verbatim}
- to
+ The full source for the sample pinger is found in
\begin{verbatim}
- DUCC_HOME/resources/service_monitors
+ DUCC_HOME/examples/src/org/apache/uima/ducc/ping/SamplePing.java
\end{verbatim}
- If these ping registrations are set up, the pinger may be run as either an
- internal thread in the SM by specifying {\em org.apache.uima.ducc.ping.SamplePing}
- in a service registration, or as an external process to the SM by
- specifying {\em org.apache.uima.ducc.ping.SamplePing.external}.
-
- If run as an internal thread, the {\em service\_ping\_arguments} may be overridden
- by any referencing service. If run as an external process, any of the
- pre-registered arguments may be overridden by reference services.
-
- The following arguments are specified in a single single comma-delimited
- string containing the following initializaton parameters:
+ The following arguments are accepted by this pinger and may be specified in a single single
+ comma-delimited string containing the following initialization parameters:
\begin{description}
\item[meta-timeout] Defines how long to wait for {\em get\_meta} to return.
\item[broker-jmx-port] Defines the JMX port of the service's broker.
@@ -604,7 +590,7 @@ public class CustomPing
queue depth is 0, even if consumer are connected. Otherwise
we do not shrink if consumers are attached to the queue.
\item[goal] The multiplier of the ActiveMQ Broker's {\em average enqeue}
- time to attemp to maintain by managing the number of instances.
+ time to attempt to maintain by managing the number of instances.
\end{description}
@@ -638,7 +624,7 @@ public class CustomPing
to determine the number of slots in the windows.
\paragraph{Lines 176-177}
- These lines initialze the DUCC-supplied {\em UimaAsServiceMonitor} that
+ These lines initialize the DUCC-supplied {\em UimaAsServiceMonitor} that
queries the UIMA-AS queues, and it resets the queue statistics via JMX so the
monitor can make accurate measurements.
@@ -649,7 +635,7 @@ public class CustomPing
\paragraph{Lines 191-240}
These lines define the required {\em getStatistics} method. This
- method collelcts ActiveMQ statistics, issue {\em get-meta} to the
+ method collects ActiveMQ statistics, issue {\em get-meta} to the
service to see if it is responding, sets the formatted information
string into the ping reply, and invokes the code to calculate a
potential redeployment of service instances.
@@ -657,7 +643,7 @@ public class CustomPing
\paragraph{Lines 245-248}
These lines override the optional {\em getLastUse} method which
simply returns the time of last known use of the service. The actual
- value is calcultated in the pinger-specific {\em calculateNewDeployment}
+ value is calculated in the pinger-specific {\em calculateNewDeployment}
method, described below.
\paragraph{Lines 253-298}
@@ -673,7 +659,7 @@ public class CustomPing
\paragraph{Lines 407-410}
These lines override the optional {\em getAdditions} method. The method
- returns the number of new service intances required to meet performance
+ returns the number of new service instances required to meet performance
goals, as calculated in
\hyperref[subsec:services.calculate-new]{\em calculateNewDeployment}.
@@ -753,7 +739,7 @@ public class CustomPing
Similarly, the {\em shrinkage window} is used to govern shrinkage. All slots must be
filled, indicating the service has been over-provisioned for a while, before a request
- is made to delete instances. The number of instnaces is never reduced below the
+ is made to delete instances. The number of instances is never reduced below the
configured {\em min} value. As well, this particular pinger never shrinks by more than
a single instance at a time, on the reasoning that it is more costly to start a new
service than to maintain one for too long. Only if there is no long-term use of
@@ -782,8 +768,8 @@ public class CustomPing
return to the SM as the last known use of this service by some process.
\paragraph{Lines 267}
- This line calculates the number of Java threads per service instance, needed to calclate the
- maxium capacity of the service in its current deployment.
+ This line calculates the number of Java threads per service instance, needed to calculate the
+ maximum capacity of the service in its current deployment.
(Note that in each UIMA-AS service, UIMA-AS itself occupies one thread, used to
manage the service, and this thread manifests itself as a consumer
@@ -882,7 +868,7 @@ public class CustomPing
is expensive we conservatively use $r < .5$ instead and make a mark
in the shrinkage window.
- Otherwise we clear the mark in the shinkage window.
+ Otherwise we clear the mark in the shrinkage window.
\paragraph{Lines 367-396}
Finally we sum across the shrinkage and expansion windows. If either