LUDOC-210 jobstats: Clarify jobstats section and add ALPS

Clarified the jobstats section of the documentation by separating the
environment variable values for jobid_var from the special values for
jobid_var.  The special values are now explained in paragraphs with
examples following the table.  The table's columns were swapped
because it is really the job scheduler which determines the value of
jobid_var.  The description preceding the table was clarified.  A
run-on sentence was split up at the beginning of section 12.2.1, and
the article "a" was added before client.

Signed-off-by: Ryan Haasken <haasken@cray.com>
Change-Id: I9f92891ad44ab3e86d81042d0978d32d9603ecfd
Reviewed-on: http://review.whamcloud.com/8577
Tested-by: Jenkins
Reviewed-by: Patrick Farrell <paf@cray.com>
Reviewed-by: Chris Horn <hornc@cray.com>
Reviewed-by: Richard Henwood <richard.henwood@intel.com>

diff --git a/LustreMonitoring.xml b/LustreMonitoring.xml
index 9fb5055..6137e71 100644 (file)
--- a/LustreMonitoring.xml
+++ b/LustreMonitoring.xml
@@ -340,7 +340,7 @@ Lustre Jobstats</title>
     <section remap="h3">
       <title><indexterm><primary>monitoring</primary><secondary>jobstats</secondary></indexterm>
 Enable/Disable Jobstats</title>
-      <para>Jobstats are disabled by default, the current state of jobstats can be verified by checking <literal>lctl get_param jobid_var</literal> on client:</para>
+      <para>Jobstats are disabled by default.  The current state of jobstats can be verified by checking <literal>lctl get_param jobid_var</literal> on a client:</para>
       <screen>
 $ lctl get_param jobid_var
 jobid_var=disable
@@ -352,7 +352,9 @@ jobid_var=disable
         job ID on each client. To permanently enable jobstats on the <literal>testfs</literal> file
         system:</para>
       <screen>$ lctl conf_param testfs.sys.jobid_var=SLURM_JOB_ID</screen>
-      <para>The value of <literal>jobid_var</literal> can be:</para>
+      <para>The following table shows the environment variables which are set by various job schedulers.
+       Set <literal>jobid_var</literal> to the value for your job scheduler to collect statistics on a
+       per job basis.</para>
     <informaltable frame="all">
       <tgroup cols="2">
         <colspec colname="c1" colwidth="50*"/>
@@ -360,75 +362,72 @@ jobid_var=disable
         <thead>
           <row>
             <entry>
-              <para><emphasis role="bold">Value</emphasis></para>
+              <para><emphasis role="bold">Job Scheduler</emphasis></para>
             </entry>
             <entry>
-              <para><emphasis role="bold">Job Scheduler</emphasis></para>
+              <para><emphasis role="bold">Environment Variable</emphasis></para>
             </entry>
           </row>
         </thead>
         <tbody>
           <row>
             <entry>
-              <para>SLURM_JOB_ID</para>
-            </entry>
-            <entry>
               <para>Simple Linux Utility for Resource Management (SLURM)</para>
             </entry>
-          </row>
-          <row>
-            <entry>
-              <para>JOB_ID</para>
-            </entry>
             <entry>
-              <para>Sun Grid Engine (SGE)</para>
+              <para>SLURM_JOB_ID</para>
             </entry>
           </row>
           <row>
             <entry>
-              <para>LSB_JOBID</para>
+              <para>Sun Grid Engine (SGE)</para>
             </entry>
             <entry>
-              <para>Load Sharing Facility (LSF)</para>
+              <para>JOB_ID</para>
             </entry>
           </row>
           <row>
             <entry>
-              <para>LOADL_STEP_ID</para>
+              <para>Load Sharing Facility (LSF)</para>
             </entry>
             <entry>
-              <para>Loadleveler</para>
+              <para>LSB_JOBID</para>
             </entry>
           </row>
           <row>
             <entry>
-              <para>PBS_JOBID</para>
+              <para>Loadleveler</para>
             </entry>
             <entry>
-              <para>Portable Batch Scheduler (PBS)/MAUI</para>
+              <para>LOADL_STEP_ID</para>
             </entry>
           </row>
           <row>
             <entry>
-              <para>procname_uid</para>
+              <para>Portable Batch Scheduler (PBS)/MAUI</para>
             </entry>
             <entry>
-              <para>process name and user ID (for debugging, or if no job scheduler is in use)</para>
+              <para>PBS_JOBID</para>
             </entry>
           </row>
           <row>
             <entry>
-              <para>disable</para>
+              <para>Cray Application Level Placement Scheduler (ALPS)</para>
             </entry>
             <entry>
-              <para>disable jobstats</para>
+              <para>ALPS_APP_ID</para>
             </entry>
           </row>
         </tbody>
       </tgroup>
     </informaltable>
-    <para>To disable jobstats specify the <literal>jobid_var</literal> as <literal>disable</literal>:</para>
+    <para>There are two special values for <literal>jobid_var</literal>: <literal>disable</literal>
+       and <literal>procname_uid</literal>.  To disable jobstats, specify <literal>jobid_var</literal>
+       as <literal>disable</literal>:</para>
     <screen>$ lctl conf_param testfs.sys.jobid_var=disable</screen>
+    <para>To track job stats per process name and user ID (for debugging, or if no job scheduler is in use),
+       specify <literal>jobid_var</literal> as <literal>procname_uid</literal>:</para>
+    <screen>$ lctl conf_param testfs.sys.jobid_var=procname_uid</screen>
     </section>
     <section remap="h3">
       <title><indexterm><primary>monitoring</primary><secondary>jobstats</secondary></indexterm>