doc/html/jobacct_gatherplugins.shtml

<!--#include virtual="header.txt"-->

<h1><a name="top">SLURM Job Accounting Gather Plugin API</a></h1>

<h2> Overview</h2>
<p> This document describes SLURM job accounting gather plugins and the API that
defines them. It is intended as a resource to programmers wishing to write
their own SLURM job accounting gather plugins. This is version 1 of the API.


<p>SLURM job accounting gather plugins must conform to the
SLURM Plugin API with the following specifications:

<p><span class="commandline">const char
plugin_name[]="<i>full&nbsp;text&nbsp;name</i>"</span>
<p style="margin-left:.2in">
A free-formatted ASCII text string that identifies the plugin.

<p><span class="commandline">const char
plugin_type[]="<i>major/minor</i>"</span><br>
<p style="margin-left:.2in">
The major type must be &quot;jobacct_gather.&quot;
The minor type can be any suitable name
for the type of accounting package. We currently use
<ul>
<li><b>aix</b>&#151; Gathers information from AIX /proc table and adds this
information to the standard rusage information also gathered for each job.
<li><b>linux</b>&#151;Gathers information from Linux /proc table and adds this
information to the standard rusage information also gathered for each job.
<li><b>none</b>&#151;No information gathered.
</ul>
The <b>sacct</b> program can be used to display gathered data from regular
accounting and from these plugins.
<p>The programmer is urged to study
<span class="commandline">src/plugins/jobacct_gather/linux</span> and
<span class="commandline">src/common/jobacct_common.c/.h</span>
for a sample implementation of a SLURM job accounting gather plugin.
<p class="footer"><a href="#top">top</a>


<h2>API Functions</h2>
<p>All of the following functions are required. Functions which are not
implemented must be stubbed.

<p class="commandline">jobacctinfo_t *jobacct_gather_p_create(jobacct_id_t *jobacct_id)
<p style="margin-left:.2in"><b>Description</b>:<br>
jobacct_gather_p_alloc() used to alloc a pointer to and initialize a
new jobacctinfo structure.<br><br>
You will need to free the information returned by this function!
<p style="margin-left:.2in"><b>Arguments</b>: <br>
<span class="commandline">tid</span>
(input) id of the task send in (uint16_t)NO_VAL if no specfic task.
<p style="margin-left:.2in"><b>Returns</b>: <br>
<span class="commandline">jobacctinfo structure pointer</span> on success, or<br>
<span class="commandline">NULL</span> on failure.

<p class="commandline">void jobacct_gather_p_destroy(jobacctinfo_t *jobacct)
<p style="margin-left:.2in"><b>Description</b>:<br>
jobacct_gather_p_free() used to free the allocation made by jobacct_gather_p_alloc().
<p style="margin-left:.2in"><b>Arguments</b>: <br>
<span class="commandline">jobacct</span>
(input) structure to be freed.<br>
<span class="commandline">none</span>
<p style="margin-left:.2in"><b>Returns</b>: <br>
<span class="commandline">none</span>

<p class="commandline">
int jobacct_gather_p_setinfo(jobacctinfo_t *jobacct,
                      enum jobacct_data_type type, void *data)
<p style="margin-left:.2in"><b>Description</b>:<br>
jobacct_gather_p_setinfo() is called to set the values of a jobacctinfo_t to
specific values based on inputs.
<p style="margin-left:.2in"><b>Arguments</b>: <br>
<span class="commandline">jobacct</span>
(input/output) structure to be altered.<br>
<span class="commandline">type</span>
(input) enum of specific part of jobacct to alter.<br>
<span class="commandline">data</span>
(input) corresponding data to set jobacct part to.
<p style="margin-left:.2in"><b>Returns</b>: <br>
<span class="commandline">SLURM_SUCCESS</span> on success, or<br>
<span class="commandline">SLURM_ERROR</span> on failure.

<p class="commandline">
int jobacct_gather_p_getinfo(jobacctinfo_t *jobacct,
                      enum jobacct_data_type type, void *data)
<p style="margin-left:.2in"><b>Description</b>:<br>
jobacct_gather_p_getinfo() is called to get the values of a jobacctinfo_t
specific values based on inputs.
<p style="margin-left:.2in"><b>Arguments</b>: <br>
<span class="commandline">jobacct</span>
(input) structure to be queried.<br>
<span class="commandline">type</span>
(input) enum of specific part of jobacct to get.<br>
<span class="commandline">data</span>
(output) corresponding data to from jobacct part.
<p style="margin-left:.2in"><b>Returns</b>: <br>
<span class="commandline">SLURM_SUCCESS</span> on success, or<br>
<span class="commandline">SLURM_ERROR</span> on failure.

<p class="commandline">
void jobacct_gather_p_pack(jobacctinfo_t *jobacct, Buf buffer)
<p style="margin-left:.2in"><b>Description</b>:<br>
jobacct_gather_p_pack() pack jobacctinfo_t in a buffer to send across the network.
<p style="margin-left:.2in"><b>Arguments</b>: <br>
<span class="commandline">jobacct</span>
(input) structure to pack.<br>
<span class="commandline">buffer</span>
(input/output) buffer to pack structure into.
<p style="margin-left:.2in"><b>Returns</b>: <br>
<span class="commandline">none</span>

<p class="commandline">
void jobacct_gather_p_unpack(jobacctinfo_t *jobacct, Buf buffer)
<p style="margin-left:.2in"><b>Description</b>:<br>
jobacct_gather_p_unpack() unpack jobacctinfo_t from a buffer received from
the network.
You will need to free the jobacctinfo_t returned by this function!
<p style="margin-left:.2in"><b>Arguments</b>: <br>
<span class="commandline">jobacct</span>
(input/output) structure to fill.<br>
<span class="commandline">buffer</span>
(input) buffer to unpack structure from.<br>
<p style="margin-left:.2in"><b>Returns</b>:
<span class="commandline">SLURM_SUCCESS</span> on success, or<br>
<span class="commandline">SLURM_ERROR</span> on failure.

<p class="commandline">
void jobacct_gather_p_aggregate(jobacctinfo_t *dest, jobacctinfo_t *from)
<p style="margin-left:.2in"><b>Description</b>:<br>
jobacct_gather_p_aggregate() is called to aggregate and get max values from two
different jobacctinfo structures.
<p style="margin-left:.2in"><b>Arguments</b>: <br>
<span class="commandline">dest</span>
(input/output) initial structure to be applied to.<br>
<span class="commandline">from</span>
(input) new info to apply to dest.
<p style="margin-left:.2in"><b>Returns</b>: <br>
<span class="commandline">none</span>

<p class="footer"><a href="#top">top</a>

<p class="commandline">int jobacct_gather_p_startpoll(int frequency)
<p style="margin-left:.2in"><b>Description</b>:<br>
jobacct_gather_p_startpoll() is called at the start of the slurmstepd,
this starts a thread that should poll information to be queried at any time
during throughout the end of the process.
Put global initialization here.
<p style="margin-left:.2in"><b>Arguments</b>: <br>
<span class="commandline">frequency</span> (input) poll frequency for polling
thread.
<p style="margin-left:.2in"><b>Returns</b>: <br>
<span class="commandline">SLURM_SUCCESS</span> on success, or<br>
<span class="commandline">SLURM_ERROR</span> on failure.

<p class="commandline">int jobacct_gather_p_endpoll()
<p style="margin-left:.2in"><b>Description</b>:<br>
jobacct_gather_p_endpoll() is called when the process is finished to stop the
polling thread.
<p style="margin-left:.2in"><b>Arguments</b>: <br>
<span class="commandline">none</span>
<p style="margin-left:.2in"><b>Returns</b>: <br>
<span class="commandline">SLURM_SUCCESS</span> on success, or<br>
<span class="commandline">SLURM_ERROR</span> on failure.

<p class="commandline">void jobacct_gather_p_suspend_poll()
<p style="margin-left:.2in"><b>Description</b>:<br>
jobacct_gather_p_suspend_poll() is called when the process is suspended.
This causes the polling thread to halt until the process is resumed.
<p style="margin-left:.2in"><b>Arguments</b>: <br>
<span class="commandline">none</span>
<p style="margin-left:.2in"><b>Returns</b>: <br>
<span class="commandline">none</span>

<p class="commandline">void jobacct_gather_p_resume_poll()
<p style="margin-left:.2in"><b>Description</b>:<br>
jobacct_gather_p_resume_poll() is called when the process is resumed.
This causes the polling thread to resume operation.
<p style="margin-left:.2in"><b>Arguments</b>:<br>
<span class="commandline">none</span>
<p style="margin-left:.2in"><b>Returns</b>:<br>
<span class="commandline">none</span>

<p class="commandline">int jobacct_gather_p_set_proctrack_container_id(uint32_t id)
<p style="margin-left:.2in"><b>Description</b>:<br>
jobacct_gather_p_set_proctrack_container_id() is called after the
proctrack container id is known at the start of the slurmstepd,
if using a proctrack plugin to track processes this will set the head
of the process tree in the plugin.
<p style="margin-left:.2in"><b>Arguments</b>: <br>
<span class="commandline">id</span> (input) procktrack container id.
<p style="margin-left:.2in"><b>Returns</b>: <br>
<span class="commandline">SLURM_SUCCESS</span> on success, or<br>
<span class="commandline">SLURM_ERROR</span> on failure.

<p class="commandline">int jobacct_gather_p_add_task(pid_t pid, uint16_t tid)
<p style="margin-left:.2in"><b>Description</b>:<br>
jobacct_gather_p_add_task() used to add a task to the poller.
<p style="margin-left:.2in"><b>Arguments</b>: <br>
<span class="commandline"> pid</span> (input) Process id <br>
<span class="commandline"> tid</span> (input) slurm global task id
<p style="margin-left:.2in"><b>Returns</b>: <br>
<span class="commandline">SLURM_SUCCESS</span> on success, or<br>
<span class="commandline">SLURM_ERROR</span> on failure.

<p class="commandline">jobacctinfo_t *jobacct_gather_p_stat_task(pid_t pid)
<p style="margin-left:.2in"><b>Description</b>:<br>
jobacct_gather_p_stat_task() used to get most recent information about task.
You need to FREE the information returned by this function!
<p style="margin-left:.2in"><b>Arguments</b>: <br>
<span class="commandline"> pid</span> (input) Process id
<p style="margin-left:.2in"><b>Returns</b>: <br>
<span class="commandline">jobacctinfo structure pointer</span> on success, or<br>
<span class="commandline">NULL</span> on failure.

<p class="commandline">jobacctinfo_t *jobacct_gather_p_remove_task(pid_t pid)
<p style="margin-left:.2in"><b>Description</b>:<br>
jobacct_gather_p_remove_task() used to remove a task from the poller.
You need to FREE the information returned by this function!
<p style="margin-left:.2in"><b>Arguments</b>: <br>
<span class="commandline"> pid</span> (input) Process id
<p style="margin-left:.2in"><b>Returns</b>: <br>
<span class="commandline">Pointer to removed jobacctinfo_t structure</span>
on success, or <br>
<span class="commandline">NULL</span> on failure.

<p class="commandline">
void jobacct_gather_p_2_sacct(sacct_t *sacct, jobacctinfo_t *jobacct)
<p style="margin-left:.2in"><b>Description</b>:<br>
jobacct_gather_p_2_sacct() is called to transfer information from data structure
jobacct to structure sacct.
<p style="margin-left:.2in"><b>Arguments</b>: <br>
<span class="commandline">sacct</span>
(input/output) initial structure to be applied to.<br>
<span class="commandline">jobacct</span>
(input) jobacctinfo_t structure containing information to apply to sacct.
<p style="margin-left:.2in"><b>Returns</b>: <br>
<span class="commandline">none</span>

<p class="footer"><a href="#top">top</a>


<h2>Parameters</h2>
<p>These parameters can be used in the slurm.conf to set up type of
plugin and the frequency at which to gather information about running jobs.
<dl>
<dt><span class="commandline">JobAcctGatherType</span>
<dd>Specifies which plugin should be used.
<dt><span class="commandline">JobAcctGatherFrequency</span>
<dd>Let the plugin know how long between pollings.
</dl>

<h2>Versioning</h2>
<p> This document describes version 1 of the SLURM Job Accounting Gather API. Future
releases of SLURM may revise this API. A job accounting gather plugin conveys its
ability to implement a particular API version using the mechanism outlined
for SLURM plugins.
<p class="footer"><a href="#top">top</a>

<p style="text-align:center;">Last modified 11 September 2007</p>

<!--#include virtual="footer.txt"-->