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 2013/01/02 20:12:11 UTC
svn commit: r1427917 [6/8] - in
/uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook: ./ images/
images/ducc-overview/ images/job-manager/ part-admin/ part-admin/admin/
part-introduction/ part-user/ part-user/cli/ unused/
Added: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/chapter-webserver.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/chapter-webserver.xml?rev=1427917&view=auto
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/chapter-webserver.xml (added)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/chapter-webserver.xml Wed Jan 2 19:12:10 2013
@@ -0,0 +1,730 @@
+<?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="ducc.vm.ov">
+ <title>Webserver</title>
+
+ <para>
+ <emphasis>The source for this chapter is ducc_ducbook/documents/chapter-webserver.xml</emphasis>
+ </para>
+
+ <para> The DUCC Web Server default address is accessed from the
+ URL <filename>http://wshost:42133</filename>. Each local installation configures the host for
+ "wshost" and may override the default port of <emphasis>42133</emphasis>
+ </para>
+
+ <para>
+ The Webserver is designed to be mostly self-documenting. The design is intentionally simple and
+ contains a link to this document. Column headers and reason/state codes have display a short
+ description if you hover your mouse over it.
+ </para>
+
+ <para>
+ The columns can all be sorted by clicking on the column headers.
+ </para>
+
+ <section>
+ <title>Common Links</title>
+
+ <para>
+ Every page contains a common header containing links and controls. The links permit navigation to other
+ content at the site. The controls provide page-wise configuration of the content at that page.
+ </para>
+
+ <para>
+ The following links are available on every page of the web server:
+ <variablelist>
+ <varlistentry>
+ <term><emphasis role="bold">Authentication</emphasis></term>
+ <listitem>
+ <simplelist>
+ <member>Login - Authenticate and start a session with the Web Server.</member>
+ <member>Logout - Terminate the Web Server session</member>
+ </simplelist>
+ <note><para>Authentication is in order to <emphasis>cancel</emphasis>
+ jobs and reservations, to create a reservation, and to perform administration.
+ It is not required to simply view the pages.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">DuccBook</emphasis></term>
+ <listitem>
+ <para>
+ This is a link to the HTML version of the documnet you are reading.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Jobs</emphasis></term>
+ <listitem>
+ <para>
+ This navigates to the Jobs page, showing all the jobs in the system.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Reservations</emphasis></term>
+ <listitem>
+ <para>
+ This navigates to the Reservations page, showing all the reservations in the system and
+ provides a button that can be used to request new reservations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Services</emphasis></term>
+ <listitem>
+ <para>
+ This navigates to the Services page, showing all the services in the system.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">System</emphasis></term>
+ <listitem>
+ <para>
+ This opens a submenu with system-related links:
+ <simplelist>
+ <member>Administration - This opens a page with administrative functions.</member>
+ <member>Classes - This shows all the scheduling classes defined to the system.</member>
+ <member>Daemons - This shows the status of DUCC's management processes.</member>
+ <member>DuccBook - This manual.</member>
+ <member>Machines - This shows the status of all the ducc worker nodes.</member>
+ </simplelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ </section>
+
+ <section>
+ <title>Jobs Page</title>
+ <para>
+ The Web Server's home page is also the Jobs page. This page has links to all the rest of the content
+ at the site and shows the status of all the jobs in the system.
+ </para>
+
+ <para>
+ The Jobs page contains the following columns:
+
+ <variablelist>
+
+ <varlistentry>
+ <term><emphasis role="bold">Id</emphasis></term>
+ <listitem>
+ <para>
+ This is the ID as assigned by DUCC. This field is hyperlinked to a "Job Details" page that shows the breakdown
+ of all the processes assigned to the job and their state.
+ </para>
+ </listitem>
+
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Start</emphasis></term>
+ <listitem><para>This is the time the Job is accepted into DUCC.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">End</emphasis></term>
+ <listitem><para>This is the time the Job completes.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">User</emphasis></term>
+ <listitem><para>This is the userid of the job owner.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Class</emphasis></term>
+ <listitem><para>This is the resource class the job is submitted to.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">State</emphasis></term>
+ <listitem>
+ <para>
+ This shows the state of the job.
+ States include:
+ <simplelist>
+ <member><emphasis role="bold">Received</emphasis> - The jobhas ben vetted, persisted, and assigned a unique ID.</member>
+ <member><emphasis role="bold">WaitingForDriver</emphasis> - The job is waiting for the Job Driver to initialize.</member>
+ <member><emphasis role="bold">WaitingForServices</emphasis> - The job is waiting to verify that any declared services are available.</member>
+ <member><emphasis role="bold">WaitingForResources</emphasis> - The job is waiting to be scheduled.</member>
+ <member><emphasis role="bold">Initializing</emphasis> - The job is in its initializaiton phase.</member>
+ <member><emphasis role="bold">Running</emphasis> - At least one process is now initialized and running.</member>
+ <member><emphasis role="bold">Completing</emphasis> - The last process has finished and the job is cleaning up.</member>
+ <member><emphasis role="bold">Completed</emphasis> - The job is complete.</member>
+ </simplelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Reason</emphasis></term>
+ <listitem>
+ <para>
+ This is information relating to completion state.
+ <simplelist>
+ <member><emphasis role="bold">EndOfJob</emphasis> - The job ran with no errors.</member>
+
+ <member><emphasis role="bold">Error</emphasis> - All work items are processes but at
+ least one had an error.</member>
+
+ <member><emphasis role="bold">CanceledByDriver</emphasis> - The Job Driver (JD)
+ terminated the job. The reason for termination is seen by hovering over the text
+ with your mouse.</member>
+
+ <member><emphasis role="bold">CanceledBySystem</emphasis> - The job was canceled
+ because DUCC was shutdown.</member>
+
+ <member><emphasis role="bold">CanceledBySser</emphasis> - The job owner or DUCC
+ administator canceled the job.</member>
+
+ <member><emphasis role="bold">DriverInitializationFailure</emphasis> - The Job
+ Deiver (JD) process is unable to initialize. Hover over the field with your mouse
+ for details (if any are available), and check your JD log.</member>
+
+ <member><emphasis role="bold">DriverProcessFailed</emphasis> - The Job Driver (JD)
+ process failed for some reason. Hover over the field with your mouse for details (if any), and
+ check your JD log.</member>
+
+ <member><emphasis role="bold">ServicesUnavailable</emphasis> - The job declared a
+ dependency on one or more services, and the Service Manager (SM) cannot find or
+ start the required service.</member>
+
+ <member><emphasis role="bold">Premature</emphasis> - The job was terminated for some
+ unknown reason before all work items were processed. Check the JP logs for details.</member>
+
+ <member><emphasis role="bold">ProcessInitializationFailure</emphasis> - Too many
+ processes failed during initialization. Check the JP logs for the reason.</member>
+
+ <member><emphasis role="bold">ProcessFailure</emphasis> - Too many
+ processes failed while running. Check the JP logs for the reason.</member>
+
+ <member><emphasis role="bold">ResourcesUnavailable</emphasis> - The Resource Manager (RM) is
+ unable to allocate resources for the job. For non-preemptable jobs this could be because
+ the limit on that type of allocaiton is reached, or all the nodes are already allocated
+ and work cannot be preempted to make space for it. For all jobs, it could be because the
+ job class is invalid.</member>
+
+ </simplelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Processes</emphasis></term>
+ <listitem><para>This is the number of processes currently assigned to the job.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Init Fails</emphasis></term>
+ <listitem>
+ <para>
+ This is the total number of initialization failures experienced by the job. This field is hyperlinked to
+ pages showing the specific failures.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Run Fails</emphasis></term>
+ <listitem>
+ <para>
+ This is the total number of process failures experienced by the job. This field is hyperlinked to a
+ page showing the specific failures.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Size</emphasis></term>
+ <listitem><para>This is the declared memory size of the job</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Total</emphasis></term>
+ <listitem><para>This is the total number of work items declared by the job.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Done</emphasis></term>
+ <listitem><para>This is the total number of work items successfuly completed for the job.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Error</emphasis></term>
+ <listitem>
+ <para>
+ This is the total number of exceptions thrown or other errors experienced by work
+ items. This field is hyperlinked to a page showing the specific failures.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Dispatch</emphasis></term>
+ <listitem>
+ <para>
+ This is the total number CASs that are currently dispatched. This is usally
+ min(Processes * Threads, incomplete_work_items - errors)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Retry</emphasis></term>
+ <listitem>
+ <para>
+ This is the number of CASs that were retried for any reason (such as
+ timeout).
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term><emphasis role="bold">Preempt</emphasis></term>
+ <listitem>
+ <para>
+ This is the total number of processes that have been preempted to make room
+ for other work due to Fair Share.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Description</emphasis></term>
+ <listitem>
+ <para>
+ This is the descriptin string from the <emphasis>--description</emphasis>
+ string from submit.
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ </variablelist>
+ </para>
+ </section>
+
+ <section>
+ <title>Job Details Page</title>
+ <para>
+ This page shows details of all the processes that run in support of a job.
+ </para>
+
+ <para>
+ The Jobs page contains the following columns:
+
+ <variablelist>
+
+ <varlistentry>
+ <term><emphasis role="bold">Id</emphasis></term>
+ <listitem>
+ <para>
+ This is the DUCC process id (not the Operating System's processid). Process 0 is alwyas the
+ Job Driver. It is hyperlinked to <emphasis>jd.out.log</emphasis>.
+ </para>
+ </listitem>
+
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Log</emphasis></term>
+ <listitem>
+ <para>
+ This is the log name for the process. It is hyperlinked to the log itself.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Size</emphasis></term>
+ <listitem>
+ <para>
+ This is the size of the log in MB. If you find you have trouble viewing the
+ log from the web server it could be because it is too big to view in the server and
+ needs to be check directly.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Hostname</emphasis></term>
+ <listitem>
+ <para>
+ This is the name of the node where the process ran.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">PID</emphasis></term>
+ <listitem>
+ <para>
+ This is the Operating Systems' PID for the process.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">State:Scheduler</emphasis></term>
+ <listitem>
+ <para>
+ This shows the Resesource Manager state of the job. It is one of:
+ <simplelist>
+ <member><emphasis role="bold">Allocated</emphasis> - The node is still allocated for this job by the RM</member>
+ <member><emphasis role="bold">Deallocated</emphasis> - The resource manager has deallocated the shares for the job on this node.</member>
+ </simplelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Reason:Scheduler</emphasis></term>
+ <listitem>
+ <para>
+ This shows why a process is terminated, from the system's point of view.
+ <simplelist>
+ <member><emphasis role="bold">AutonomousStop</emphasis> - The process terminated
+ unexpectedly of its own accord ("crashed") for no detectable reason.. </member>
+ <member><emphasis role="bold">JobCanceled</emphasis> - The job was canceled by the user or a system administrator.</member>
+ <member><emphasis role="bold">JobCompleted</emphasis> - The process is canceled because of DUCC restart.</member>
+ <member><emphasis role="bold">JobFailure</emphasis> - The job failure limit is exceeded, causing the job to be canceled by the JD.</member>
+ <member><emphasis role="bold">Exception</emphasis> - The process is terminated by the JD exception handler.</member>
+ <member><emphasis role="bold">Failed</emphasis> - The process is terminated by the
+ Agent because the JP wrapper was able to detect and communicate a fatal condition
+ (Exception) in the pipeline..</member>
+ <member><emphasis role="bold">FailedInitialization</emphasis> - The process is terminated because the initialization step failed.</member>
+ <member><emphasis role="bold">Forced</emphasis> - The node is preempted by RM for other work because of fair share.</member>
+ <member><emphasis role="bold">InitializationTimeout</emphasis> - The initialization phase exceeded the configured timeout.</member>
+ <member><emphasis role="bold">Killed</emphasis> - The agent terminated the process for some reason.</member>
+ <!--
+ <member><emphasis role="bold">Purged</emphasis> - The node with the process exceeded its heartbeat threshold and is deactivated by the RM.</member>
+ -->
+ <member><emphasis role="bold">Stopped</emphasis> - The job is winding down, there's no more work for this node, so it stops.</member>
+ <member><emphasis role="bold">Voluntary</emphasis> - The job is winding down, there's no more work for this node, so it stops.</member>
+ <member><emphasis role="bold">Unknown</emphasis> - None of the above. This is an
+ exceptional condition. Check the JP and JD logs for possible causes..</member>
+
+
+ </simplelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">State:Agent</emphasis></term>
+ <listitem>
+ <para>
+ If there's an error detected only by the agent, this shows the Agent's reason for a process's death.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Reason:Agent</emphasis></term>
+ <listitem>
+ <para>
+ If there's an error detected only by the agent, this shows the Agent's reason for a process's death.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Time:Init</emphasis></term>
+ <listitem>
+ <para>
+ This is the clock time this process spent in initializaiton.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Time:Run</emphasis></term>
+ <listitem>
+ <para>
+ This is the clock time this process spent in executing, not including initialization.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Time:GC</emphasis></term>
+ <listitem>
+ <para>This is amount of time spent in Java Garbage Collection for the process.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Count:GC</emphasis></term>
+ <listitem>
+ <para>
+ This is the number of garbage collections performed by the process.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">%GC</emphasis></term>
+ <listitem>
+ <para>
+ Process percentage of time spent in garbage collections, relative to total of
+ initialization + run times.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">CPU</emphasis></term>
+ <listitem>
+ <para>
+ Cumulative CPU time for the process.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">%RSS</emphasis></term>
+ <listitem>
+ <para>
+ Resident Storage Size, as a percentage of process memory requirement in job specification.
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term><emphasis role="bold">Time:Avg</emphasis></term>
+ <listitem>
+ <para>
+ Average seconds spent per work item in the process.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Time:min</emphasis></term>
+ <listitem>
+ <para>
+ This is the minimum time spent per work item in the process.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Time:max</emphasis></term>
+ <listitem>
+ <para>
+ This is the minimum time spent per work item in theprocess.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Done</emphasis></term>
+ <listitem>
+ <para>
+ This is the number of work items processed in this process.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Error</emphasis></term>
+ <listitem>
+ <para>
+ This is the number of exceptions processing work items in this process.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Retry</emphasis></term>
+ <listitem>
+ <para>
+ This is the number of work items that were retried for any reason, excluding
+ preemptions.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Preempt</emphasis></term>
+ <listitem>
+ <para>
+ This is the number of work items that had to be retried because of preemption.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">JConsole URL</emphasis></term>
+ <listitem>
+ <para>
+ This is a URL that can be used to connect via JMX to the processes, e.g. via jconsole.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ </section>
+
+ <section>
+ <title>Reservation Details Page</title>
+ <para>
+ This page shows details of all reservations.
+ </para>
+
+ <para>
+ The Reservations page contains the following columns:
+
+ <variablelist>
+
+ <varlistentry>
+ <term><emphasis role="bold">Id</emphasis></term>
+ <listitem>
+ <para>
+ This is the DUCC process id of the reservation as provided when the reservation is made.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Start</emphasis></term>
+ <listitem>
+ <para>
+ This is the time the reservation was mde.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">End</emphasis></term>
+ <listitem>
+ <para>
+ This is the time the reservation was canceled.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">User</emphasis></term>
+ <listitem>
+ <para>
+ This is the userid if the person who made the reservation.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Class</emphasis></term>
+ <listitem>
+ <para>
+ This is the resource class used to schedule the reservation.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Status</emphasis></term>
+ <listitem>
+ <para>
+ This is the status of the reservation. Values include:
+ <simplelist>
+ <member><emphasis role="bold">Received</emphasis> - Reservation has been vetted, persisted, and assigned unique Id.</member>
+ <member><emphasis role="bold">WaitingForResources</emphasis> - The reservation is waitng for the Resource Manager to find
+ and schedule resources.</member>
+ <member><emphasis role="bold">Assigned</emphasis> - The reservation is active.</member>
+ <member><emphasis role="bold">Completed</emphasis> - The reservation has been canceled.</member>
+ </simplelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Reason</emphasis></term>
+ <listitem>
+ <para>
+ If a reservation is not active, the reason. Reasons include:
+ <simplelist>
+ <member><emphasis role="bold">ResourcesUnavailable</emphasis> - The Resource Manager was unable to find free or
+ freeable resources to match the resource request.</member>
+ <member><emphasis role="bold">CanceledBySystem</emphasis> - The job was canceled because DUCC was shutdown.</member>
+ <member><emphasis role="bold">CanceledByUser</emphasis> - The owner or administrator released the reservation. </member>
+ </simplelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Allocation</emphasis></term>
+ <listitem>
+ <para>
+ The number of resources (shares for FIXED policy reservartions, processes for RESERVE policy reservations) that
+ are allocated.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Size</emphasis></term>
+ <listitem>
+ <para>
+ The memory size in GB of the each allocated unit.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">List</emphasis></term>
+ <listitem>
+ <para>
+ The node names of the machines where the resource is allocated.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Description</emphasis></term>
+ <listitem>
+ <para>
+ This is the descriptin string from the <emphasis>--description</emphasis>
+ string from submit.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ </section>
+
+</chapter>
Propchange: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/chapter-webserver.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/cancel.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/cancel.xml?rev=1427917&view=auto
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/cancel.xml (added)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/cancel.xml Wed Jan 2 19:12:10 2013
@@ -0,0 +1,128 @@
+<?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.
+-->
+ <!-- ************************************ CANCEL CLI ********************************** -->
+ <section>
+ <title>ducc_cancel</title>
+
+ <para>
+ <emphasis>The source for this section is ducc_ducbook/documents/part-user/cli/cancel.xml</emphasis>
+ </para>
+
+ <para>
+ <emphasis>Description:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+
+ <para>
+ The <emphasis>cancel</emphasis> CLI is used to cancel a job that has previously been
+ submitted but which has not yet completed.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Usage:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis role="bold">Script wrapper</emphasis></term>
+ <listitem><para><emphasis>$DUCC_HOME</emphasis>/bin/ducc_cancel</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Executable Jar</emphasis></term>
+ <listitem><para>java-jar <emphasis>$DUCC_HOME</emphasis>/lib/ducc_cancel.jar</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Java main</emphasis></term>
+ <listitem><para>org.apache.uima.ducc.cli.DuccJobCancel</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>
+ If no options are given, help text is presented.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Options:</emphasis>
+ <variablelist>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--id [jobid]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ The ID is the jobid returned by the job submission.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--help</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ Prints the usage text to the console.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+
+ </section>
+
Propchange: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/cancel.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/monitor.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/monitor.xml?rev=1427917&view=auto
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/monitor.xml (added)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/monitor.xml Wed Jan 2 19:12:10 2013
@@ -0,0 +1,195 @@
+<?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.
+-->
+ <!-- ************************************ MONITOR CLI ********************************** -->
+ <section>
+ <title>ducc_monitor</title>
+
+ <para>
+ <emphasis>The source for this section is ducc_ducbook/documents/part-user/cli/monitor.xml</emphasis>
+ </para>
+
+ <para>
+ <emphasis>Description:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+
+ <para>
+ It may be desired to monitor a job's progress after it has been submitted. The
+ monitor CLI connects to the DUCC message flow and provides job status as
+ it progresses including state changes, error counts, and number of work items processed.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Usage:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis role="bold">Script wrapper</emphasis></term>
+ <listitem><para><emphasis>$DUCC_HOME</emphasis>/bin/ducc_monitor</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Executable Jar</emphasis></term>
+ <listitem><para>java-jar <emphasis>$DUCC_HOME</emphasis>/lib/ducc-monitor.jar</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Java main</emphasis></term>
+ <listitem><para>org.apache.uima.ducc.cli.DuccJobMonitor</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>
+ If no options are given, help text is presented.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Options:</emphasis>
+ <variablelist>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--cancel_job_on_interrupt</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ If the monitor is canceled with Ctrl-C,
+ the job is also canceled. Otherwise the monitor is simply disconnected and
+ the job continues.
+ </para>
+ <para>
+ If <emphasis>--wait_for_completin</emphasis> is not specified this option is ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--debug</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ Enable debugging messages. This is primarily for debugging DUCC itself.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--help</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ Prints the usage text to the console.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--id [jobid]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ The ID is the jobid returned by the job submission.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--timestamp</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ If specified, messages are timestamped.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+
+ </section>
+
Propchange: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/monitor.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/reserve.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/reserve.xml?rev=1427917&view=auto
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/reserve.xml (added)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/reserve.xml Wed Jan 2 19:12:10 2013
@@ -0,0 +1,237 @@
+<?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.
+-->
+ <!-- ************************************ RESERVE CLI ********************************** -->
+ <section>
+ <title>ducc_reserve</title>
+
+ <para>
+ <emphasis>The source for this section is ducc_ducbook/documents/part-user/cli/reserve.xml</emphasis>
+ </para>
+
+ <para>
+ <emphasis>Notes:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+
+ <para>
+ Reservations may be for full machines, or partial machines based on memory. The mechanism for
+ distinguishing which type of reservation the job class. A job class implementing the <emphasis>RESERVE</emphasis>
+ scheduling policy results in a full machine being reserved. A job clas simplementing the <emphasis>FIXED</emphasis>
+ scheduling policy results in a partial machine being reserved. The default
+ DUCC distribution configures class <emphasis>reserve</emphasis> for full machine reservations, and
+ class <emphasis>fixed</emphasis> for partial reservations.
+ </para>
+
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Description:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+
+ <para>
+ The <emphasis>reserve</emphasis> CLI is used request a reservation of resources. Reservations can
+ be for entire machines or partial machines, based on memory requirements. All reservations are persistent:
+ the resources remain dedicated to the requestor until explicitly returned. All reservations are performeed
+ on an "all-or-nothing" basis: either the entire set of requested resources is reserved, or the
+ reservation request fails.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Usage:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><emphasis role="bold">Script wrapper</emphasis></term>
+ <listitem><para><emphasis>$DUCC_HOME</emphasis>/bin/ducc_reserve</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Executble Jar</emphasis></term>
+ <listitem><para>java -jar <emphasis>$DUCC_HOME</emphasis>/lib/ducc-reserve.jar</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Java main</emphasis></term>
+ <listitem><para>org.apache.uima.ducc.cli.DuccReservationSubmit</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ <para>
+ If no options are given, help text is presented.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Options:</emphasis>
+ <variablelist>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--description [text]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ The text is any string used to describe the reservation. It is displayed in the Web Server.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--help</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ Prints the usage text to the console.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--number-of-instances [integer]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the number of full or partial machine reservations to schedule.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--instance-memory-size [KB|MB|GB|TB]]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the amount of memory the reserved machine must supoprt. For full machine reservations,
+ this is the total memory on the machine. For partial reservations, the machine may have more memory, but
+ not less than is specified.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--scheduling_class [classname]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the name of the scheuling class the RM will use to determine
+ the resource allocation for each process. The default DUCC distribution provides
+ class "reserve" for full machine reservations, and "fixed" for partial machine reservations.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--specifiecaiton [file]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ All the parameters used to request a reservation may be placed in a standard Java properties file. This file
+ may then be used to submit the request (rather than providing all the parameters directory to submit).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+
+ </section>
+
Propchange: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/reserve.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/service_cancel.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/service_cancel.xml?rev=1427917&view=auto
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/service_cancel.xml (added)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/service_cancel.xml Wed Jan 2 19:12:10 2013
@@ -0,0 +1,133 @@
+<?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.
+-->
+ <!-- ************************************ Service CANCEL CLI ********************************** -->
+ <section id="ducc.cli.service_cancel" xreflabel="ducc_service_cancel">
+ <title>ducc_service_cancel</title>
+
+ <para>
+ <emphasis>The source for this section is ducc_ducbook/documents/part-user/cli/cancel.xml</emphasis>
+ </para>
+
+ <para>
+ <emphasis>Description:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+
+ <para>
+ The <emphasis>ducc_service_cancel</emphasis> CLI is used to cancel
+ a <emphasis>submitted</emphasis> service. Generally services won't end unless
+ canceled. If this is used against a <emphasis>registered</emphasis> service instance,
+ the service manager will usually restart the service.
+ Use <emphasis><link linkend="ducc.cli.service.stop">ducc_services
+ stop</link></emphasis>
+ to stop a <emphasis>registered</emphasis> service.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Usage:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis role="bold">Script wrapper</emphasis></term>
+ <listitem><para>ducc_service_cancel</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Executable Jar</emphasis></term>
+ <listitem><para>java-jar <emphasis>$DUCC_HOME</emphasis>/lib/ducc-service-cancel.jar</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Java main</emphasis></term>
+ <listitem><para>org.apache.uima3.ducc.cli.DuccServiceCancel</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>
+ If no options are given, help text is presented.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Options:</emphasis>
+ <variablelist>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--id [serviceid]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ The ID is the jobid returned by the job submission, also available from the webserver.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--help</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ Prints the usage text to the console.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+
+ </section>
+
Propchange: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/service_cancel.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/service_submit.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/service_submit.xml?rev=1427917&view=auto
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/service_submit.xml (added)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/service_submit.xml Wed Jan 2 19:12:10 2013
@@ -0,0 +1,589 @@
+<?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.
+-->
+ <!-- ************************************ SUBMIT CLI ********************************** -->
+ <section id="ducc.cli.service_submit">
+ <title>ducc_service_submit</title>
+
+ <para>
+ <emphasis>The source for this section is ducc_ducbook/documents/part-user/cli/service_submit.xml</emphasis>
+ </para>
+
+
+ <para>
+ <emphasis>Description:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+
+ <para>
+ The <emphasis>ducc_service_submit</emphasis> CLI is used to submit a job as a <emphasis>service</emphasis>
+ to DUCC. The CLI is similar to <emphasis>ducc_submit</emphasis> with the following key differences:
+ <itemizedlist>
+ <listitem>
+ <para>
+ There is no Collection Reader.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ There is no Job monitor for services because services don't generally end of their own accord.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Service jobs must supply a fully-formed DD XML.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ On submission of a service, the DUCC CLI examines the service DD descriptor for the queue name, and
+ the supplied <emphasis>jvm_args</emphasis> for a broker URL. It forms a service ID of the following form
+ which may be referenced in the <emphasis>--service_dependency</emphasis> clauses of jobs
+ and services which are dependent on this service:
+ <screen>UIMA-AS:[endpoint]:[broker-url]</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Usage:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><emphasis role="bold">Script wrapper</emphasis></term>
+ <listitem><para><emphasis>$DUCC_HOME</emphasis>/bin/ducc_service_submit</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Executble Jar</emphasis></term>
+ <listitem><para>java -jar <emphasis>$DUCC_HOME</emphasis>/lib/ducc-service-submit.jar</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Java main</emphasis></term>
+ <listitem><para>org.apache.uima.ducc.cli.DuccServiceSubmit</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ <para>
+ If no options are given, help text is presented.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Options:</emphasis>
+ <variablelist>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--debug</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ Enable debugging messages. This is primarily for debugging DUCC itself.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--description [text]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ The text is any string used to describe the job. It is displayed in the Web Server. Example:
+ <screen>--description "This is my very sophisticated job"</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--help</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ Prints the usage text to the console.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--jvm [path-to-java]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ States the JVM to use. If not specified, the same JVM used by the Agents is
+ used. Example:
+ <screen> --jvm /share/jdk1.6/bin/java</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--log_directory [path-to-log directory]</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the path to the directory for the user logs. If not specified,
+ the default is the user's home directory. Example:<screen>--log_directory /home/bob</screen>.
+ Within this directory DUCC creates a subdirectory for each job, using the
+ numerical ID of the job. The format of the generated log file names is
+ descripbed in <xref linkend="ducc.user.logs" />.
+ </para>
+ <note>
+ <para>
+ Note that <emphasis>--log_directory</emphasis> specifies only the path to
+ a directory where logs are to be stored. In order to manage multiple processes
+ running in multiple machines DUCC, sub-directory and file names are generated
+ by DUCC and may not be directly specified.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--process_classpath [ClASSPATH]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the Java CLASSPATH to use in each Job Process (JP) and must be specified. Example:
+ <screen>--process_classpath a.jar:b.jar</screen>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--process_DD [DD descriptor]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies a UIMA Deployment Descriptor for the job processes for DD-style
+ jobs. This is mutually exclusive with <emphasis>--process_descriptor_AE,
+ --process_descriptor_CM, and --process_descriptor_CC.</emphasis> This descriptor
+ is a resource that is searched for in the CLASSPATH and data path as described
+ in the <emphasis><link linkend="ducc.cli.submit.notes">notes</link></emphasis>. For
+ example:<screen>--process_DD /home/billy/resource/DD_foo.xml</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--process_deployments_max [integer]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the maximum nunber of Job Processes to deploy at any given
+ time. <screen>--process_deployments_max 66</screen>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--process_environment [environment]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies environment parameters for the Job Processes. If present, they are added
+ to the Job Process environment as the process is spawned. It must be a quoted,
+ blank-delimeted lsit of name-value pairs. For example:
+ <screen>"--process_environment TERM=xterm DISPLAY=:1.0"</screen>
+ </para>
+ <note>
+ <para>
+ On Secure Linux systems, the environemnt variable LD_LIBRARY_PATH may not be passed
+ to the user's program. If it is necessary to pass LD_LIBRARY_PATH to the JP or
+ JD processes, it must be specified as DUCC_LD_LIBRARY_PATH. Ducc (<emphasis>securely</emphasis>)
+ passes this as LD_LIBRARY_PATH, <emphasis>after</emphasis> the JP or JD has assumed
+ the user's identity. For example:
+ <screen>"--process_environment TERM=xterm DISPLAY=:1.0 DUCC_LD_LIBRARY_PATH=/my/own/lib.so"</screen>
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--process_failures_limit [integer]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the maximum number of individual Job Process (JP) failures that are
+ to be tolerated before killing the job. The default is 15. If this limit is
+ exceeded over the lifetime of a job DUCC terminates the entire job.
+ <screen>"--process_failures_limit 23"</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--process_initialization_failures_cap [integer]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the maximum number of independent Job Process initialization
+ failures (i.e. System.exit(), kill-15...) before the number of Job Processes is
+ capped at the number in state Running currently. The default is 99.
+ Example:<screen>--process_initialization_failures_cap 62</screen>
+ </para>
+ <para>
+ Note that the job is NOT killed if there are processes that have passed initialization and
+ are running. If this limit is reached, the only action is to not start new processes
+ for the job.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--process_jvm_args [list]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies additinal arguments to be passed to the Job Process JVM.
+ Example:<screen>--process_jvm_args -Xmx400M -Xms100M</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--process_memory_size [size]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the maximum amount of RAM in GB to be allocated to each Job Process. This
+ value is used by the Resource Manager to allocate resources. if this amount is
+ exceeded by a Job Process the Agent terminates the process with a ShareSizeExceeded
+ message.
+ Example:<screen>--process_memory_size 33</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--scheduling_class [classname]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the name of the scheuling class the RM will use to determine
+ the resource allocation for each process. The names of the classes are installation
+ dependent. If not specified, the default is taken
+ from the global DUCC configuration <link linkend="ducc.properties">ducc.properties</link>.
+ Example:<screen>--schedling_class normal</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--service_dependency[list]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies a comma-delimeted list of services the job processes are dependent upon.
+ Each endpoint must be of the form UIMA-AS:<emphasis>endpoint</emphasis>:<emphasis>broker_url</emphasis>
+ where <emphasis>endpoint</emphasis> is the UIMA-AS service endpoint and <emphasis>broker_url</emphasis>
+ is the ActiveMQ broker URL.
+ </para>
+ <para>
+ In the example are two dependencies, one with endpoint RandomSleepAE and broker tcp:bluej682:61616, and the other
+ with endpoint OtherEp and broker URL tcp:bluej123:123.
+ Example:<literallayout>
+--service_dependency UIMA-AS:RandomSleepAE:tcp:bluej682:61616, \
+ UIMA-AS:OtherEp:tcp:bluej123:123
+ </literallayout>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--specifiecaiton [file]</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ All the parameters used to submit a job may be placed in a standard Java properties file. This file
+ may then be used to submit the job (rather than providing all the parameters directory to submit).
+ </para>
+ <para>
+ For example, <screen>ducc_submit --specification job.props</screen> where the <emphasis>job.props</emphasis>
+ contains:
+ <screen>
+working_directory=/Users/challngr/projects/ducc/ducc_test/test/bin
+process_failures_limit=20
+driver_environment= DUCC_LD_LIBRARY_PATH=/a/other/bogus/path
+process_environment=AE_INIT_TIME=10000 DUCC_LD_LIBRARY_PATH=/a/bogus/path
+log_directory=/Users/challngr/ducc/logs/
+process_initialization_failures_cap=99
+process_descriptor_AE=org.apache.uima.ducc.test.randomsleep.FixedSleepAE
+process_classpath=/home/bob/projects/ducky-service.jar
+description=../simple/jobs/1.job[AE]
+process_jvm_args=-Xmx100M -DdefaultBrokerURL=tcp://localhost:61616
+scheduling_class=fixed
+process_memory_size=15
+ </screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ <emphasis role="bold">--working_directory</emphasis>
+
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+ <para>
+ This specifies the working directory to be set by the Job Driver and Job Process processes. If not
+ specified, the current directory is used. Example:<screen>--working_directory /Users/challngr/projects/ducc/ducc_test/bin</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+
+ <para id="ducc.cli.service.notes">
+ <emphasis>Notes:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+
+ <para>
+ When searching for UIMA XML resource files such as descriptors, DUCC searches both the classpath and the
+ data path according to the following rules:
+ <orderedlist>
+ <listitem>
+ <para>
+ If the resource ends in .xml it is assumed the resource is a file and
+ the path is either an absolute path or a path relative to the specified
+ working directory. If the file is not found the search exits and the job
+ is terminated.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the resource does not end in .xml, DUCC creates a path by replacing the
+ "." separators with "/" and appending ".xml". It then searches the CLASSPATH
+ for the resource as a file.
+ </para>
+ <para>
+ If the resource is found in either place the search is successful. Otherwise the
+ search fails and the job is terminated.
+ </para>
+ <note>
+ <para>
+ Note that in the current implementation, resources are NOT searched for inside
+ jars in the classpath. Files must be supplied.
+ </para>
+ </note>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ </section>
+
Propchange: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/service_submit.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services.xml
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services.xml?rev=1427917&view=auto
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services.xml (added)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services.xml Wed Jan 2 19:12:10 2013
@@ -0,0 +1,178 @@
+<?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.
+-->
+ <!-- ************************************ Service Overview ********************************** -->
+ <section id="ducc.cli.service.overview" xreflabel="DUCC Service CLI Overview">
+ <title>ducc_services</title>
+
+ <para>
+ <emphasis>The source for this section is ducc_ducbook/documents/part-user/cli/service_api.xml</emphasis>
+ </para>
+
+ <para>
+ <emphasis>Description:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+
+ <para>
+ The <emphasis>ducc_services</emphasis> CLI is used to manage service registration. It
+ has a number of functions as listed below.
+ Additionally the <emphasis>ducc_services</emphasis> CLI wraps <emphasis>ducc_service_submit</emphasis>
+ and <emphasis>ducc_service_cancel</emphasis> for convenience.
+ </para>
+
+ <para>
+ The functions include:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term> <emphasis role="bold">Register</emphasis></term>
+ <listitem>
+ <para>
+ This <emphasis>registers</emphasis> a service with the Service Manager. A registered
+ service is retained by DUCC until it is unregistered.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> <emphasis role="bold">Unregister</emphasis></term>
+ <listitem>
+ <para>
+ This <emphasis>unregisters</emphasis> a service with the Service Manager. When a service
+ is unregistered DUCC optionally stops the service instance, if any, and discards all knowledge of it.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> <emphasis role="bold">Start</emphasis></term>
+ <listitem>
+ <para>
+ The <emphasis>start</emphasis> 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 service instances running if they should fail. The <emphasis>start</emphasis>
+ function is also used to increase the number of running service instances if desired.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> <emphasis role="bold">Stop</emphasis></term>
+ <listitem>
+ <para>
+ The <emphasis>stop</emphasis> function stops some or all service instances.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> <emphasis role="bold">Query</emphasis></term>
+ <listitem>
+ <para>
+ The <emphasis>query</emphasis> function returns detailed information about all known services,
+ both registerd and otherwise.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> <emphasis role="bold">Modify</emphasis></term>
+ <listitem>
+ <para>
+ The <emphasis>modify</emphasis> function allows some aspectes of a registered service to be
+ updated without re-registereing the service. It optionally alters the running service
+ instances to conform with the updates.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> <emphasis role="bold">Submit</emphasis></term>
+ <listitem>
+ <para>
+ Use the <emphasis role="bold">ducc_service_submit</emphasis> command to submit a
+ service. This is available only through the command-line wrapper.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> <emphasis role="bold">Cancel</emphasis></term>
+ <listitem>
+ <para>
+ Use the <emphasis role="bold">ducc_service_cancel</emphasis> command to cancel a
+ submitted service. This is available only through the command-line wrapper.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ <emphasis>Usage:</emphasis>
+ <variablelist>
+ <varlistentry>
+ <term />
+ <listitem>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis role="bold">Script wrapper</emphasis></term>
+ <listitem><para><emphasis>$DUCC_HOME</emphasis>/bin/ducc_services</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Executble Jar</emphasis></term>
+ <listitem><para>java -jar <emphasis>$DUCC_HOME</emphasis>/lib/ducc-services.jar</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold">Java main</emphasis></term>
+ <listitem><para>org.apache.uima.ducc.cli.DuccServiceApi</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>
+ The <emphasis role="bold">ducc_services</emphasis> CLI requires one of the verbs listed above
+ as the first argument. The subsequent arguments are determned by the verb.
+ </para>
+
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="services_register.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="services_start.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="services_stop.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="services_modify.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="services_query.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="services_sub_can.xml" />
+
+ </section>
+
Propchange: uima/sandbox/uima-ducc/trunk/uima-ducc-ducbook/docbook/part-user/cli/services.xml
------------------------------------------------------------------------------
svn:eol-style = native