# SLURM External Sensors Plugin API (ExtSensorsType)

## Overview

This document describes SLURM external sensors plugins and the API that defines them. It is intended as a resource to programmers wishing to write their own SLURM external sensors plugins.

SLURM external sensors 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 "ext_sensors." The minor type can be any suitable name for the type of external sensors. We currently use

- none— No external sensors data is collected.
- rrd—Gets external sensors data from the RRD database.

The programmer is urged to study src/plugins/ext_sensors/rrd and src/common/slurm_ext_sensors.c for a sample implementation of a SLURM external sensors plugin.

## API Functions

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

int init (void)

Description:
Called when the plugin is loaded, before any other functions are called. Put global initialization here.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

void fini (void)

Description:
Called when the plugin is removed. Clear any allocated storage here.

Returns: None.

Note: These init and fini functions are not the same as those described in the dlopen (3) system library. The C run-time system co-opts those symbols for its own initialization. The system _init() is called before the SLURM init(), and the SLURM fini() is called before the system's _fini().

extern int ext_sensors_read_conf(void)

Description:
Reads the external sensors plugin configuration file (ext_sensors.conf) and populates the configuration structure. Called by the slurmctld daemon.

Arguments:
None

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

extern int ext_sensors_free_conf(void)

Description:
Frees the memory allocated for the external sensors configuration. Called by the slurmctld daemon.

Arguments:
None

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

extern int ext_sensors_p_update_component_data(void)

Description:
Updates external sensors data for data types and component types as configured in ext_sensors.conf. Called by the slurmctld daemon.

Arguments:
None

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

extern int ext_sensors_p_get_stepstartdata(struct step_record *step_rec)

Description:
Sets external sensors data in the step record when a job step starts. Called by slurmctld.

Arguments:
step_rec (input) pointer to step record.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

extern int ext_sensors_p_get_stependdata(struct step_record *step_rec)

Description:
Sets external sensors data in the step record when a job step ends. Called by slurmctld.

Arguments:
step_rec (input) pointer to step record.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

## Parameters

These parameters can be used in the slurm.conf to configure the plugin and the frequency at which to gather external sensors data.

ExtSensorsType
  Specifies which external sensors plugin should be used.
ExtSensorsFreq
  Time interval between pollings in seconds.

## Versioning

This document describes version 1 of the SLURM External Sensors Plugin API. Future releases of SLURM may revise this API. A, energy accounting plugin conveys its ability to implement a particular API version using the mechanism outlined for SLURM plugins.

Last modified 8 May 2014