SLURM Job Accounting Gather Plugin API
Overview
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.
SLURM job accounting gather plugins must conform to the SLURM Plugin API with the following specifications:
const char
plugin_name[]="full text name"
A free-formatted ASCII text string that identifies the plugin.
const char
plugin_type[]="major/minor"
The major type must be "jobacct_gather."
The minor type can be any suitable name
for the type of accounting package. We currently use
The programmer is urged to study
src/plugins/jobacct_gather/linux and
src/common/jobacct_common.c/.h
for a sample implementation of a SLURM job accounting gather plugin.
All of the following functions are required. Functions which are not
implemented must be stubbed.
jobacctinfo_t *jobacct_gather_p_create(jobacct_id_t *jobacct_id)
Description: Arguments: Returns: void jobacct_gather_p_destroy(jobacctinfo_t *jobacct)
Description: Arguments: Returns:
int jobacct_gather_p_setinfo(jobacctinfo_t *jobacct,
enum jobacct_data_type type, void *data)
Description: Arguments: Returns:
int jobacct_gather_p_getinfo(jobacctinfo_t *jobacct,
enum jobacct_data_type type, void *data)
Description: Arguments: Returns:
void jobacct_gather_p_pack(jobacctinfo_t *jobacct, Buf buffer)
Description: Arguments: Returns:
void jobacct_gather_p_unpack(jobacctinfo_t *jobacct, Buf buffer)
Description: Arguments: Returns:
SLURM_SUCCESS on success, or
void jobacct_gather_p_aggregate(jobacctinfo_t *dest, jobacctinfo_t *from)
Description: Arguments: Returns: int jobacct_gather_p_startpoll(int frequency)
Description: Arguments: Returns: int jobacct_gather_p_endpoll()
Description: Arguments: Returns: void jobacct_gather_p_suspend_poll()
Description: Arguments: Returns: void jobacct_gather_p_resume_poll()
Description: Arguments: Returns: int jobacct_gather_p_set_proctrack_container_id(uint32_t id)
Description: Arguments: Returns: int jobacct_gather_p_add_task(pid_t pid, uint16_t tid)
Description: Arguments: Returns: jobacctinfo_t *jobacct_gather_p_stat_task(pid_t pid)
Description: Arguments: Returns: jobacctinfo_t *jobacct_gather_p_remove_task(pid_t pid)
Description: Arguments: Returns:
void jobacct_gather_p_2_sacct(sacct_t *sacct, jobacctinfo_t *jobacct)
Description: Arguments: Returns: 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.
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.
Last modified 11 Sep 2007
The sacct program can be used to display gathered data from regular
accounting and from these plugins.
API Functions
jobacct_gather_p_alloc() used to alloc a pointer to and initialize a
new jobacctinfo structure.
You will need to free the information returned by this function!
tid
(input) id of the task send in (uint16_t)NO_VAL if no specfic task.
jobacctinfo structure pointer on success, or
NULL on failure.
jobacct_gather_p_free() used to free the allocation made by jobacct_gather_p_alloc().
jobacct
(input) structure to be freed.
none
none
jobacct_gather_p_setinfo() is called to set the values of a jobacctinfo_t to
specific values based on inputs.
jobacct
(input/output) structure to be altered.
type
(input) enum of specific part of jobacct to alter.
data
(input) corresponding data to set jobacct part to.
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.
jobacct_gather_p_getinfo() is called to get the values of a jobacctinfo_t
specific values based on inputs.
jobacct
(input) structure to be queried.
type
(input) enum of specific part of jobacct to get.
data
(output) corresponding data to from jobacct part.
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.
jobacct_gather_p_pack() pack jobacctinfo_t in a buffer to send across the network.
jobacct
(input) structure to pack.
buffer
(input/output) buffer to pack structure into.
none
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!
jobacct
(input/output) structure to fill.
buffer
(input) buffer to unpack structure from.
SLURM_ERROR on failure.
jobacct_gather_p_aggregate() is called to aggregate and get max values from two
different jobacctinfo structures.
dest
(input/output) initial structure to be applied to.
from
(input) new info to apply to dest.
none
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.
frequency (input) poll frequency for polling
thread.
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.
jobacct_gather_p_endpoll() is called when the process is finished to stop the
polling thread.
none
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.
jobacct_gather_p_suspend_poll() is called when the process is suspended.
This causes the polling thread to halt until the process is resumed.
none
none
jobacct_gather_p_resume_poll() is called when the process is resumed.
This causes the polling thread to resume operation.
none
none
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.
id (input) procktrack container id.
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.
jobacct_gather_p_add_task() used to add a task to the poller.
pid (input) Process id
tid (input) slurm global task id
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.
jobacct_gather_p_stat_task() used to get most recent information about task.
You need to FREE the information returned by this function!
pid (input) Process id
jobacctinfo structure pointer on success, or
NULL on failure.
jobacct_gather_p_remove_task() used to remove a task from the poller.
You need to FREE the information returned by this function!
pid (input) Process id
Pointer to removed jobacctinfo_t structure
on success, or
NULL on failure.
jobacct_gather_p_2_sacct() is called to transfer information from data structure
jobacct to structure sacct.
sacct
(input/output) initial structure to be applied to.
jobacct
(input) jobacctinfo_t structure containing information to apply to sacct.
none
Parameters
Versioning