# SLURM Job Accounting Storage Plugin API

## Overview

This document describes SLURM Job Accounting Storage plugins and the API that defines them. It is intended as a resource to programmers wishing to write their own SLURM Job Accounting Storage plugins. This is version 1 of the API.

SLURM Job Accounting Storage 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_storage." The minor type can be any suitable name for the type of accounting package. We currently use

- filetxt—Information written to a text file.
- mysql— Store information in a mysql database.
- pgsql— Store information in a postgresql database.
- none— Information is not stored anywhere.

The programmer is urged to study src/plugins/jobacct_storage/mysql for a sample implementation of a SLURM Job Accounting Storage plugin.

The Job Accounting Storage plugin was written to be a interface to storage data collected by the Job Accounting Gather plugin. When adding a new database you may want to add common functions in a common file in the src/common dir. Refer to src/common/mysql_common.c/.h for an example so other plugins can also use that database type to write out information.

## API Functions

The Job Accounting Storage API uses hooks in the slurmctld.

All of the following functions are required. Functions which are not implemented must be stubbed.

#### Functions called by the jobacct_storage plugin

int jobacct_storage_p_init(char *location)

Description:
jobacct_storage_p_init() is called to initiate a connection to the database server and check the state of the database table to make sure they are in sync with the table definitions in the plugin. Put global initialization here. Or open file or anything to initialize the plugin.

Arguments:
location (input) database name or log file location.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int jobacct_storage_p_fini()

Description:
jobacct_storage_p_fini() is called at the end of the program that has called jobacct_storage_p_init this function closes the connection to the database or logfile.

Arguments:
none

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int jobacct_storage_p_job_start(struct job_record *job_ptr)

Description:
jobacct_storage_p_job_start() is called in the jobacct plugin when a job starts, inserting information into the database about the new job.

Arguments:
job_ptr (input) information about the job in slurmctld.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int jobacct_storage_p_job_complete(struct job_record *job_ptr)

Description:
jobacct_storage_p_job_complete() is called in the jobacct plugin when a job completes, this updates info about end of a job.

Arguments:
job_ptr (input) information about the job in slurmctld.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int jobacct_storage_p_step_start(struct step_record *step_ptr)

Description:
jobacct_storage_p_step_start() is called in the jobacct plugin at the allocation of a new step in the slurmctld, this inserts info about the beginning of a step.

Arguments:
step_ptr (input) information about the step in slurmctld.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int jobacct_storage_p_step_complete(struct step_record *step_ptr)

Description:
jobacct_storage_p_step_complete() is called in the jobacct plugin at the end of a step in the slurmctld, this updates the ending information about a step.

Arguments:
step_ptr (input) information about the step in slurmctld.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int jobacct_storage_p_suspend(struct job_record *job_ptr)

Description:
jobacct_storage_p_suspend() is called in the jobacct plugin when a job is suspended or resumed in the slurmctld, this updates the database about the suspended time of the job.

Arguments:
job_ptr (input) information about the job in slurmctld.

Returns:
none

void jobacct_storage_p_get_jobs(List job_list, List selected_steps, List selected_parts, void *params)

Description:
jobacct_storage_p_get_jobs() is called to get a list of jobs from the database given the specific inputs.

Arguments:
List job_list (input/output) list to be filled with jobacct_job_rec_t.
List selected_steps (input) list containing type jobacct_select_step_t to query against.
List selected_parts (input) list containing char *'s of names of partitions to query against.
void *params (input) to be cast as sacct_parameters_t in the plugin.

jobacct_job_rec_t, jobacct_select_step_t, and sacct_parameters_t are all defined in common/slurm_jobacct.h

Returns:
none

void jobacct_storage_p_archive(List selected_parts, void *params)

Description:
database_p_jobcomp_archive() used to archive old data.

Arguments:
List selected_parts (input) list containing char *'s of names of partitions to query against.
void *params (input) to be cast as sacct_parameters_t in the plugin.

Returns:
none

## Parameters

These parameters can be used in the slurm.conf to set up connections to the database all have defaults based on the plugin type used.

JobAcctStorageType
  Specifies which plugin should be used.
JobAcctStorageLoc
  Let the plugin the name of the logfile/database name to use.
JobAcctStorageHost
  Let the plugin know the host where the database is.
JobAcctStoragePort
  Let the plugin know the port to connect to.
JobAcctStorageUser
  Let the plugin know the name of the user to connect to the database with.
JobAcctStoragePass
  Let the plugin know the password of the user connecting to the database.

## Versioning

This document describes version 1 of the SLURM Job Accounting Storage API. Future releases of SLURM may revise this API. A Job Accounting Storage plugin conveys its ability to implement a particular API version using the mechanism outlined for SLURM plugins.

Last modified 23 May 2007