Author: challngr Date: Wed Jun 12 17:16:43 2013 New Revision: 1492293 URL: http://svn.apache.org/r1492293 Log: UIMA-2682 Duccbook updates.
Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-monitor.tex uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-perf-stats.tex uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-services.tex uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-unreserve.tex Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-monitor.tex URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-monitor.tex?rev=1492293&r1=1492292&r2=1492293&view=diff ============================================================================== --- uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-monitor.tex (original) +++ uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-monitor.tex Wed Jun 12 17:16:43 2013 @@ -1,3 +1,8 @@ +%% +%% ducc_monitor is currently unsupported. Perhaps it will come back after +%% release 1. So the doc skeleton is preserved. +%% + % Create well-known link to this spot for HTML version \ifpdf \else @@ -14,21 +19,21 @@ \paragraph{Usage:} \begin{description} \item[Executable Jar] java -jar \ducchome/lib/uima-ducc-monitor.jar {\em options} - \item[Script wrapper] java -jar \ducchome/bin/ducc-monitor {\em options} + \item[Script wrapper] \ducchome/bin/ducc-monitor {\em options} \item[Java Main] java -cp \ducchome/lib/uima-ducc-monitor.jar org.apache.uima.ducc.cli.DuccJobMonitor {\em options} \end{description} \paragraph{Options:} \begin{description} - \item[--debug ] + \item[$--$debug ] Prints internal debugging information, intended for DUCC developers or extended problem determination. - \item[--id {[jobid]}] + \item[$--$id {[jobid]}] The ID is the id of the job to monitor. - \item[--help] + \item[$--$help] Prints the usage text to the console. - \item[--quiet] + \item[$--$quiet] Disable CLI informational miessages; - \item[timestamp] + \item[--timestamp] Enables timestamps on the monitor messages. \end{description} Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-perf-stats.tex URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-perf-stats.tex?rev=1492293&r1=1492292&r2=1492293&view=diff ============================================================================== --- uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-perf-stats.tex (original) +++ uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-perf-stats.tex Wed Jun 12 17:16:43 2013 @@ -20,10 +20,10 @@ \paragraph{Options:} \begin{description} - \item[--job id] This specifies the job to report on. - \item[--directory dir] This specifies the job's log directory. (DUCC writes usage information into this - directory.) - \item[--report {[summary or workitems or processes]}] + \item[$--$job id] This specifies the job to report on. + \item[$--$directory dir] This specifies the job's log directory. (DUCC writes usage information into this + directory as the job is running.) + \item[$--$report {[summary or workitems or processes]}] This specifies the type of report: \begin{description} \item[summary] This produces a per-AE summary of the performance of that AE, including @@ -37,7 +37,7 @@ maximum memory usage, page faults, swap space in use, maximum swap used, \%CPU, garbage collection statistics, and work item statistics (processed, errors, retried, etc.). \end{description} - \item[--help] Prints the usage text to the console. + \item[$--$help] Prints the usage text to the console. \end{description} \paragraph{Notes:} Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-services.tex URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-services.tex?rev=1492293&r1=1492292&r2=1492293&view=diff ============================================================================== --- uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-services.tex (original) +++ uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-services.tex Wed Jun 12 17:16:43 2013 @@ -16,6 +16,14 @@ \item[Register] This registers a service with the Service Manager by saving a service specification in the Service Manager's registration area. The specification is retained by DUCC until it is unregistered. + + The registration consists primarily of a service specification identical to that used + with \hyperref[sec:cli.service-submit]{ducc\_submit\_service}. This specification is + used when the Service Manager needs to start a service instance. A second properties + file, the {\em meta properties} for the service, contains additional state and + management properties. The registered properties for a service are made available for + viewing from the DUCC Web Server's \hyperref[sec:ws-service-details]{service details} + page. \item[Unregister] This unregisters a service with the Service Manager. When a service is unregistered DUCC optionally stops the service instance, if any, and discard the @@ -52,28 +60,28 @@ \subsection{Common Options} These options are common to all of the service verbs: \begin{description} - \item[--debug ] + \item[$--$debug ] Prints internal debugging information, intended for DUCC developers or extended problem determination. - \item[--help] + \item[$--$help] Prints the usage text to the console. \end{description} - \subsection{ducc\_services --register Options} + \subsection{ducc\_services $--$register Options} \label{subsec:cli.ducc-services.register} The {\em register} function submits a service specification to DUCC. DUCC stores this information until it is {\em unregistered}. Once registered, a service may be started, stopped, etc. \begin{description} - \item[--register {[specification file] [options]}] The specification file is optional. If + \item[$--$register {[specification file] [options]}] The specification file is optional. If specified, it has the same contents as described for the \hyperref[sec:cli.service-submit]{{\em ducc\_service\_submit}} command. As with {\em ducc\_service\_submit}, any of the keywords in the specification may be overriden on the command line. - \item[--autostart {[true or false]}] This indicates whether to register the service as + \item[$--$autostart {[true or false]}] This indicates whether to register the service as an autostarted service. If not specified, the default is {\em false}. - \item[--instances {[n]}] This specifies the number of instances to start when the service + \item[$--$instances {[n]}] This specifies the number of instances to start when the service is started. If not specified, the default is 1. \item[Other keywords] These are the same as described for \hyperref[sec:cli.service-submit]{{\em @@ -81,7 +89,7 @@ \end{description} - \subsection{ducc\_services --start Options} + \subsection{ducc\_services $--$start Options} The start function instructs DUCC to alllocate resources for a service and to start it in those resources. The service remains running until explictly stopped. DUCC will attempt to keep the @@ -89,7 +97,7 @@ number of running service instances if desired. \begin{description} - \item[--start {[service-id or endpoint]}] This indicates that a service is to be started. The service id + \item[$--$start {[service-id or endpoint]}] This indicates that a service is to be started. The service id is either the numeric ID assigned by DUCC when the service is registered, or the service endpoint string. Example: \begin{verbatim} @@ -97,38 +105,38 @@ ducc_services --start 23 ducc_services --start UIMA-AS:Service23:tcp://bob.com:12345 \end{verbatim} - \item[--instances {[integer]}] This is the number of instances to start. If omitted, sufficient + \item[$--$instances {[integer]}] This is the number of instances to start. If omitted, sufficient instances to match the registered number are started. If more than the registered number of instances is running this command has no effect. - If the number is specified, the number is added + If the number of instances is specified, the number is added to the currently number of running instances. Thus if five instances are running and \begin{verbatim} - ducc\_services --start 33 --instances 5\ + ducc_services --start 33 --instances 5 \end{verbatim} is issued, five more service instances are started for service 33 for a totoal of ten, - regardless of the number specified in the registration. The registry is updatedo if the + regardless of the number specified in the registration. The registry is updated if the {\em --update} option is also specified. Examples: \begin{verbatim} ducc_services --start 23 --intances 5 ducc_services --start UIMA-AS:Service23:tcp://bob.com:12345 --instances 3 --update \end{verbatim} - \item[--update]If specified, the registry is updated to the total number of started + \item[$--$update]If specified, the registry is updated to the total number of started instances. Example: \begin{verbatim} ducc_services --start UIMA-AS:Service23:tcp://bob.com:12345 --instances 3 --update \end{verbatim} \end{description} - \subsection{ducc\_services --stop Options} + \subsection{ducc\_services $--$stop Options} The stop function instructs DUCC to stop some number of service instances. If no specific number is specified, all instances are stopped. This is used only for registered services. Use \hyperref[sec:cli.service-cancel]{{\em ducc\_service\_cancel}} command to stop submitted services. \begin{description} - \item[--stop {[service-id or endpoint]}] This specifies the service to be stopped. The service id + \item[$--$stop {[service-id or endpoint]}] This specifies the service to be stopped. The service id is either the numeric ID assigned by DUCC when the service is registered, or the service endpoint string. Example: \begin{verbatim} @@ -136,17 +144,17 @@ ducc_services --stop 23 ducc_services --stop UIMA-AS:Service23:tcp://bob.com:12345 \end{verbatim} - \item[--instances {[integer]}] This is the number of instances to stop. If omitted, all - instances for the service are stopped. If a number is specified, then only the specified - number of instances are stopped. Thus if ten instances are running for a service - with numeric id {\em 33} and + \item[$--$instances {[integer]}] This is the number of instances to stop. If omitted, all + instances for the service are stopped. If the number of instances is specified, then only + the specified number of instances are stopped. Thus if ten instances are running for a + service with numeric id 33 and \begin{verbatim} ducc_services --stop 33 --instances 5 \end{verbatim} is issued, five (randomly selected) service instances are stopped for service 33, leaving five running. The registry is updated if the {\em --update} option is - specified. The registered number of instances is never reduced to 0 even if the number of - running instances is reduced to 0. + specified. The registered number of instances is never reduced to zero even if the number of + running instances is reduced to zero. Example: \begin{verbatim} @@ -154,19 +162,19 @@ ducc_services --stop 23 --intances 5 ducc_services --stop UIMA-AS:Service23:tcp://bob.com:12345 --instances 3 \end{verbatim} - \item[--update] If specified, the registry is updated to the total number of instances - remaining, but is never reduced below 1. Example: + \item[$--$update] If specified, the registry is updated to the total number of instances + remaining, but is never reduced below one (1). Example: \begin{verbatim} ducc_services --stop UIMA-AS:Service23:tcp://bob.com:12345 --instances 3 --update \end{verbatim} \end{description} - \subsection{ducc\_services --modify Options} + \subsection{ducc\_services $--$modify Options} The modify function dynamically updates some of the attributes of a registered service. \begin{description} - \item[--modify {[service-id or endpoint]}] This identifies the service to modify. The service id is either + \item[$--$modify {[service-id or endpoint]}] This identifies the service to modify. The service id is either the numeric ID assigned by DUCC when the service is registered, or the service endpoint string. Example: \begin{verbatim} @@ -175,7 +183,7 @@ ducc_services --modify UIMA-AS:Service23 \end{verbatim} \item[ --instances {[integer]}] This updates the number of services instances that are - started when the service is started. Only the registration is updated. If the {\em --activate} + started when the service is started. Only the registration is updated. If the {\em $--$activate} option is also specified, running instances are stopped or started as needed to match the new number. @@ -196,23 +204,31 @@ ducc_services --modify UIMA-AS:Service23 \item[ --autostart {["true" or "false"]}] This changes the autostart property for the registered services. When set to "true", the service is started automatically when the - DUCC system is started. - + DUCC system is started. If the service is not currently started, it will now start + with the registered number of instances. If the service is running, the instances + remain running. + + One way to think of this is: if {\em autostart} is true, DUCC will attempt to keep + the registered number of instances running at all times. If {\em autostart} is + false, all instance start and stop is manual. Example: \begin{verbatim} ducc_services --stop UIMA-AS:Service23:tcp://bob.com:12345 --autostart false \end{verbatim} \end{description} - \subsection{ducc\_services -query Options} + \subsection{ducc\_services $--$query Options} The query function returns details about all known services of all types and classes, including the DUCC ids of the service instances (for submitted and registered services), the DUCC ids of the jobs using each service, and a summary of each service's queue and performance statistics, when available. + All information returned by {\em ducc\_services $--$query} is also available via the + \hyperref[ws:services-page]{Services Page} of the Web Server as well as the DUCC Service API (see + the \href{apidocs/index.html}{JavaDoc}). \begin{description} - \item[--query {[service-id or endpoint]}] This indicates that a service is to be stopped. The + \item[$--$query {[service-id or endpoint]}] This indicates that a service is to be stopped. The service id is either the numeric ID assigned by DUCC when the service is registered, or the service endpoint string. @@ -220,16 +236,17 @@ ducc_services --stop UIMA-AS:Service23:t Below is a query against a system with three services. - The service with endpoint {\tt UIMA-AS:FixedSleepAE\_6:tcp://bobmach291:61617} is a service - submitted outside of DUCC so it is marked as Implicit and has no implementing processes - tha are known to DUCC. It is used by job 0 and is active, available, and being actively - pinged. The ActiveMq queue statistics are shown. + The service with endpoint {\tt UIMA-AS:FixedSleepAE\_6:tcp://bobmach291:61617} is a service + submitted outside of DUCC so it is marked as Implicit and has no implementing processes tha + are known to DUCC. It is used by job 0 (``References'') and is active, available, and being + actively pinged. The ActiveMq queue statistics are shown. The service with endpoint {\tt UIMA-AS:FixedSleepAE\_5:tcp://bobmach:61617} is a registered service, whose registered numeric id is 2. It is registered for two instnaces and no autostart. Since it is not autostarted, it will be terminated when it is no longer used. It will linger for 5 seconds after the last referencing job completes, in case a subsequent job - that uses it enters the system (not a realistic linger time!). It is currently used (referenced) + that uses it enters the system (not a realistic linger time!). It has two active + instances whose DUCC Ids are 9 and 5. It is currently used (referenced) by DUCC jobs 1 and 5. The service with endpoint {\tt UIMA-AS:FixedSleepAE\_1:tcp://bobmach:61617} is a Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-unreserve.tex URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-unreserve.tex?rev=1492293&r1=1492292&r2=1492293&view=diff ============================================================================== --- uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-unreserve.tex (original) +++ uima/sandbox/uima-ducc/trunk/uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-unreserve.tex Wed Jun 12 17:16:43 2013 @@ -18,13 +18,13 @@ \paragraph{Options:} \begin{description} - \item[--debug ] + \item[$--$debug ] Prints internal debugging information, intended for DUCC developers or extended problem determination. - \item[--id {[jobid]}] + \item[$--$id {[jobid]}] The ID is the id of the reservation to cancel. - \item[--help] + \item[$--$help] Prints the usage text to the console. - \item[--role\_administrator] The command is being issued in the role of a DUCC administrator. + \item[$--$role\_administrator] The command is being issued in the role of a DUCC administrator. If the user is not also a registered administrator this flag is ignored. (This helps to protect administrators from inadvertantly canceling jobs they do not own.) \end{description}