# External Sensors Plugin API (ExtSensorsType)

## Overview

This document describe. 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.

const uint32_t plugin_version
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 loaded 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.

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(step_record_t *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(step_record_t *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.

>

Last modified 23 October 2019