/usr/share/doc/slurm-wlm-doc/html/jobcompplugins.html is in slurm-wlm-doc 17.11.2-1build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 | <!DOCTYPE html>
<html lang="en-US">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width" />
<title>Slurm Workload Manager</title>
<link rel="shortcut icon" href="favicon.ico" />
<link rel="stylesheet" type="text/css" href="fonts.css" />
<link rel="stylesheet" type="text/css" href="reset.css" />
<link rel="stylesheet" type="text/css" href="style.css" />
<link rel="stylesheet" type="text/css" href="slurm.css" />
<script src="jquery.min.js"></script>
</head>
<body>
<div class="container container--main">
<header class="site-header" role="banner">
<div class="site-masthead">
<h1 class="site-masthead__title site-masthead__title--slurm">
<a href="/" rel="home">
<span class="slurm-logo">Slurm Workload Manager</span>
</a>
</h1>
<div class="site-masthead__title">
<a href="https://www.schedmd.com/" rel="home">
<span class="site-logo">SchedMD</span>
</a>
</div>
<button class="site-masthead__trigger menu-trigger" type="button" role="button" aria-label="Toggle Navigation"><span class="menu-trigger__lines"></span></button>
</div>
<nav class="site-nav">
<h2 class="site-nav__title">Navigation</h2>
<div class="slurm-title">
<div class="slurm-logo"><a href="/">Slurm Workload Manager</a></div>
<div class="slurm-title__version">Version 17.11</div>
</div>
<ul class="site-nav__menu site-menu menu" role="navigation">
<li class="site-menu__item">
<div>About</div>
<ul>
<li><a href="overview.html">Overview</a></li>
<li><a href="news.html">What's New</a></li>
<li><a href="team.html">Slurm Team</a></li>
<li><a href="meetings.html">Meetings</a></li>
<li><a href="testimonials.html">Testimonials</a></li>
<li><a href="disclaimer.html">Legal Notices</a></li>
</ul>
</li>
<li class="site-menu__item">
<div>Using</div>
<ul>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="documentation.html">Documentation</a></li>
<li><a href="faq.html">FAQ</a></li>
<li><a href="publications.html">Publications</a></li>
</ul>
</li>
<li class="site-menu__item">
<div>Installing</div>
<ul>
<li><a href="download.html">Download</a></li>
<li><a href="quickstart_admin.html">Installation Guide</a></li>
</ul>
</li>
<li class="site-menu__item">
<div>Getting Help</div>
<ul>
<li><a href="https://www.schedmd.com/services.php">Support</a></li>
<li><a href="mail.html">Mailing Lists</a></li>
<li><a href="https://www.schedmd.com/services.php">Training</a></li>
<li><a href="troubleshoot.html">Troubleshooting</a></li>
</ul>
</li>
</ul>
</nav>
</header>
<div class="content" role="main">
<section class="slurm-search">
<div class="container" id="cse">
<gcse:search></gcse:search>
</div>
</section>
<div class="section">
<div class="container">
<h1><a name="top">Slurm Job Completion Logging Plugin API</a></h1>
<h2> Overview</h2>
<p>This document describes Slurm job completion logging plugins and the API that defines
them. It is intended as a resource to programmers wishing to write their own SLURM
job completion logging plugins.</p>
<p>Slurm job completion logging plugins are Slurm plugins that implement the SLURM
API for logging job information upon their completion. This may be used to log job information
to a text file, database, etc. The plugins must conform to the Slurm Plugin API with the following
specifications:</p>
<p><span class="commandline">const char plugin_type[]</span><br>
The major type must be "jobcomp." The minor type can be any recognizable
abbreviation for the type of scheduler. We recommend, for example:</p>
<ul>
<li><b>none</b> — No job logging.</li>
<li><b>filetxt</b> — Log job information to a text file.</li>
<li><b>mysql</b> — Job completion is written to a mysql database.</li>
<li><b>script</b> — Execute a script passing in job information in environment variables.</li>
</ul>
<p><span class="commandline">const char plugin_name[]</span><br>
Some descriptive name for the plugin.
There is no requirement with respect to its format.</p>
<p><span class="commandline">const uint32_t plugin_version</span><br>
If specified, identifies the version of Slurm used to build this plugin and
any attempt to load the plugin from a different version of Slurm will result
in an error.
If not specified, then the plugin may be loadeed by Slurm commands and
daemons from any version, however this may result in difficult to diagnose
failures due to changes in the arguments to plugin functions or changes
in other Slurm functions used by the plugin.</p>
<p>The programmer is urged to study
<span class="commandline">src/plugins/jobcomp/filetxt/jobcomp_filetxt.c</span> and
<span class="commandline">src/plugins/jobcomp/none/jobcomp_none.c</span>
for sample implementations of a Slurm job completion logging plugin.</p>
<p class="footer"><a href="#top">top</a></p>
<h2>Data Objects</h2>
<p>The implementation must maintain (though not necessarily directly export) an
enumerated <span class="commandline">errno</span> to allow Slurm to discover
as practically as possible the reason for any failed API call. Plugin-specific enumerated
integer values should be used when appropriate. It is desirable that these values
be mapped into the range ESLURM_JOBCOMP_MIN and ESLURM_JOBCOMP_MAX
as defined in <span class="commandline">slurm/slurm_errno.h</span>.
The error number should be returned by the function
<a href="#get_errno"><span class="commandline">slurm_jobcomp_get_errno()</span></a>
and this error number can be converted to an appropriate string description using the
<a href="#strerror"><span class="commandline">slurm_jobcomp_strerror()</span></a>
function described below.</p>
<p>These values must not be used as return values in integer-valued functions
in the API. The proper error return value from integer-valued functions is SLURM_ERROR.
The implementation should endeavor to provide useful and pertinent information by
whatever means is practical.
Successful API calls are not required to reset any errno to a known value. However,
the initial value of any errno, prior to any error condition arising, should be
SLURM_SUCCESS. </p>
<p class="footer"><a href="#top">top</a></p>
<h2>API Functions</h2>
<p>The following functions must appear. Functions which are not implemented should be stubbed.</p>
<p class="commandline"> int init (void)
<p style="margin-left:.2in"><b>Description</b>:<br>
Called when the plugin is loaded, before any other functions are
called. Put global initialization here.
<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>
<p class="commandline"> void fini (void)
<p style="margin-left:.2in"><b>Description</b>:<br>
Called when the plugin is removed. Clear any allocated storage here.
<p style="margin-left:.2in"><b>Returns</b>: None.</p>
<p><b>Note</b>: These init and fini functions are not the same as those
described in the <span class="commandline">dlopen (3)</span> system library.
The C run-time system co-opts those symbols for its own initialization.
The system <span class="commandline">_init()</span> is called before the SLURM
<span class="commandline">init()</span>, and the SLURM
<span class="commandline">fini()</span> is called before the system's
<span class="commandline">_fini()</span>.</p>
<p class="commandline">int slurm_jobcomp_set_location (char * location);</p>
<p style="margin-left:.2in"><b>Description</b>: Specify the location to be used for job logging.</p>
<p style="margin-left:.2in"><b>Argument</b>:<span class="commandline"> location</span>
(input) specification of where logging should be done. The interpretation of
this string is at the discretion of the plugin implementation.</p>
<p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful. On failure,
the plugin should return SLURM_ERROR and set the errno to an appropriate value
to indicate the reason for failure.</p>
<p class="footer"><a href="#top">top</a></p>
<p class="commandline">int slurm_jobcomp_log_record (struct job_record *job_ptr);</p>
<p style="margin-left:.2in"><b>Description</b>: Note that a job is about to
terminate or change size. The job's state will include the JOB_RESIZING flag
if and only if it is about to change size. Otherwise the job is terminating.
Note the existence of <i>resize_time</i> in the job record if one wishes to
record information about a job at each size (i.e. a history of the job as
its size changes through time).</p>
<p style="margin-left:.2in"><b>Argument</b>: <br>
<span class="commandline"> job_ptr</span> (input) Pointer to
job record as defined in <i>src/slurmctld/slurmctld.h</i></p>
<p style="margin-left:.2in"><b>Returns</b>: SLURM_SUCCESS if successful. On failure,
the plugin should return SLURM_ERROR and set the errno to an appropriate value
to indicate the reason for failure.</p>
<p class="footer"><a href="#top">top</a></p>
<a name="get_errno"><p class="commandline">int slurm_jobcomp_get_errno (void);</p></a>
<p style="margin-left:.2in"><b>Description</b>: Return the number of a
job completion logger specific error.</p>
<p style="margin-left:.2in"><b>Arguments</b>: None</p>
<p style="margin-left:.2in"><b>Returns</b>: Error number for the last failure encountered by the job completion logging plugin.</p>
<p class="footer"><a href="#top">top</a></p>
<p class="commandline"><a name="strerror">const char *slurm_jobcomp_strerror(int errnum);</a></p>
<p style="margin-left:.2in"><b>Description</b>: Return a string description of a job completion logger specific error code.</p>
<p style="margin-left:.2in"><b>Arguments</b>:
<span class="commandline"> errnum</span> (input) a job completion logger
specific error code.</p>
<p style="margin-left:.2in"><b>Returns</b>: Pointer to string describing the error
or NULL if no description found in this plugin.</p>
<p class="footer"><a href="#top">top</a></p>
<p class="commandline">
List slurm_jobcomp_get_jobs(acct_job_cond_t *job_cond);</a></p>
<p style="margin-left:.2in"><b>Description</b>: Get completed job info from
storage.</p>
<p style="margin-left:.2in"><b>Arguments</b>:<br>
<span class="commandline"> job_cond</span>
(input) specification of filters to identify the jobs we wish information about
(start time, end time, cluster name, user id, etc).
acct_job_cond_t is defined in common/slurm_accounting_storage.h.
<p style="margin-left:.2in"><b>Returns</b>: A list of job records or NULL on
error. Elements on the list are of type jobcomp_job_rec_t, which is
defined in common/slurm_jobcomp.h.
Any returned list must be destroyed to avoid memory leaks.
<p class="footer"><a href="#top">top</a></p>
<p class="commandline">
void slurm_jobcomp_archive(List selected_parts, void *params)
<p style="margin-left:.2in"><b>Description</b>: used to archive old data.
<p style="margin-left:.2in"><b>Arguments</b>: <br>
<span class="commandline">List selected_parts </span>
(input) list containing char *'s of names of partitions to query against.<br>
<span class="commandline">void *params </span>
(input) to be cast as sacct_parameters_t in the plugin.
<p style="margin-left:.2in"><b>Returns</b>: None</p>
<p class="footer"><a href="#top">top</a></p>
<p class="footer"><a href="#top">top</a></p>
<p style="text-align:center;">Last modified 27 March 2015</p>
</div> <!-- END .container -->
</div> <!-- END .section -->
</div> <!-- END .content -->
</div> <!-- END .main -->
<footer class="site-footer" role="contentinfo">
<nav class="footer-nav section">
<div class="container">
<p><a href="disclaimer.html" target="_blank" class="privacy">Legal Notices</a></p>
</div>
</nav>
</footer>
</body>
</html>
|