Slurm Profile Accounting Plugin API (AcctGatherProfileType)

Overview

This document describes Slurm profile accounting plugins and the API that defines them. It is intended as a resource to programmers wishing to write their own Slurm profile accounting plugins.
このドキュメントでは、Slurmプロファイルアカウンティングプラグインとそれらを定義するAPIについて説明します。独自のSlurmプロファイルアカウンティングプラグインを作成したいプログラマへのリソースとして意図されています。

A profiling plugin allows more detailed information on the execution of jobs than can reasonably be kept in the accounting database. (All jobs may also not be profiled.) A seperate User Guide documents how to use the hdf5 version of the plugin. An influxdb plugin is also available since Slurm 17.11.
プロファイリングプラグインを使用すると、アカウンティングデータベースに適切に保持できるよりも詳細なジョブの実行情報を取得できます。（すべてのジョブがプロファイルされない場合もあります。）別のユーザーガイドには、プラグインのhdf5バージョンの使用方法が記載されています。Sflum 17.11以降、influxdbプラグインも利用可能です。

The plugin provides an API for making calls to store data at various points in a step's lifecycle. It collects data periodically from potentially several sources. The periodic samples are eventually consolidated into one time series dataset for each node of a job.
プラグインは、ステップのライフサイクルのさまざまな時点でデータを保存するための呼び出しを行うためのAPIを提供します。潜在的にいくつかのソースから定期的にデータを収集します。定期的なサンプルは最終的に、ジョブのノードごとに1つの時系列データセットに統合されます。

The plugin's primary work is done within slurmstepd on the compute nodes. It assumes a shared file system, presumably on the management network. This avoids having to transfer files back to the controller at step end. Data is typically gathered at job_acct_gather interval or acct_gather_energy interval and the volume is not expected to be burdensome.
プラグインの主要な作業は、計算ノードのslurmstepd内で行われます。おそらく管理ネットワーク上にある共有ファイルシステムを想定しています。これにより、ステップの最後にファイルをコントローラーに転送し直す必要がなくなります。通常、データはjob_acct_gather間隔またはacct_gather_energy間隔で収集され、ボリュームに負荷がかかることは想定されていません。

The hdf5 and influxdb implementations record I/O counts from the network interface (Interconnect), I/O counts from the node from the Lustre parallel file system, disk I/O counts, cpu and memory utilization for each task, and a record of energy use.
hdf5とinfluxdbの実装は、ネットワークインターフェイス（Interconnect）からのI / Oカウント、Luster並列ファイルシステムからのノードからのI / Oカウント、ディスクI / Oカウント、各タスクのCPUとメモリの使用率、およびエネルギー使用。

The hdf5 implementation stores this data in a HDF5 file for each step on each node for the jobs. A separate program (sh5util) is provided to consolidate all the node-step files in one container for the job. HDF5 is a well known structured data set that allows different types of related data to be stored in one file. Its internal structure resembles a file system with groups being similar to directories and data sets being similar to files. There are commodity programs, notably HDF5View for viewing and manipulating these files. sh5util also provides some capability for extracting subsets of date for import into other analysis tools like spreadsheets.
hdf5実装は、ジョブの各ノードの各ステップのHDF5ファイルにこのデータを格納します。別のプログラム（sh5util）が提供され、すべてのノードステップファイルをジョブの1つのコンテナーに統合します。HDF5は、さまざまなタイプの関連データを1つのファイルに格納できるようにする、よく知られた構造化データセットです。その内部構造は、ファイルシステムに似ており、グループはディレクトリに、データセットはファイルに似ています。これらのファイルを表示および操作するための商品プログラム、特にHDF5Viewがあります。sh5utilは、スプレッドシートのような他の分析ツールにインポートするために日付のサブセットを抽出するためのいくつかの機能も提供します。

This plugin is incompatible with --enable-front-end. It you need to simulate a large configuration, please use --enable-multiple-slurmd.

Slurm profile accounting plugins must conform to the Slurm Plugin API with the following specifications:
このプラグインは--enable-front-endと互換性がありません。大規模な構成をシミュレートする必要がある場合は、-enable-multiple-slurmdを使用してください。Slurmプロファイルアカウンティングプラグインは、次の仕様でSlurmプラグインAPIに準拠する必要があります。

const char plugin_name[]="full text name"

A free-formatted ASCII text string that identifies the plugin.
プラグインを識別する自由形式のASCIIテキスト文字列。

const char plugin_type[]="major/minor"

The major type must be "acct_gather_profile." The minor type can be any suitable name for the type of profile accounting. We currently use
主なタイプは「acct_gather_profile」でなければなりません。マイナータイプは、プロファイルアカウンティングのタイプに適した任意の名前にすることができます。現在使用しています

• none — No profile data is gathered.
  none —プロファイルデータは収集されません。
  
• hdf5 — Gets profile data about energy use, i/o sources (Lustre, network) and task data such as local disk i/o, CPU and memory usage.
  hdf5 —エネルギー使用に関するプロファイルデータ、I / Oソース（Lustre、ネットワーク）、およびローカルディスクI / O、CPU、メモリ使用量などのタスクデータを取得します。
  

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.
指定した場合、このプラグインのビルドに使用されたSlurmのバージョンを識別し、異なるバージョンのSlurmからプラグインをロードしようとすると、エラーが発生します。指定されていない場合、プラグインはSlurmコマンドとデーモンによって任意のバージョンから読み込まれる可能性がありますが、プラグイン関数の引数の変更やプラグインによって使用される他のSlurm関数の変更が原因で、障害の診断が困難になる場合があります。

The programmer is urged to study src/plugins/acct_gather_profile/acct_gather_profile_hdf5.c and src/common/slurm_acct_gather_profile.c for a sample implementation of a Slurm profile accounting plugin.
Slurmプロファイルアカウンティングプラグインのサンプル実装については、src / plugins / acct_gather_profile / acct_gather_profile_hdf5.cおよびsrc / common / slurm_acct_gather_profile.c。

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().
注：これらのinitおよびfini関数は、dlopen（3）システムライブラリで説明されているものと同じではありません。Cランタイムシステムは、独自の初期化のためにこれらのシンボルを選択します。システムの_init（）はSlurm init（）の前に呼び出され、Slurm fini（）はシステムの_fini（）の前に呼び出されます。

void acct_gather_profile_g_conf_options(void)

Description:
Called from slurmstepd between fork() and exec() of application. Close open files
アプリケーションのfork（）とexec（）の間でslurmstepdから呼び出されます。開いているファイルを閉じる

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

void acct_gather_profile_g_conf_options(s_p_options_t **full_options, int *full_options_cnt)

Description:
Defines configuration options in acct_gather.conf
acct_gather.confの構成オプションを定義します

Arguments:
full(out) option definitions.
full（out）オプションの定義。
full_options_cnt(out) number in full.
full_options_cnt（out）完全な番号。

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

void acct_gather_profile_g_conf_set(s_p_hashtbl_t *tbl)

Description:
Set configuration options from acct_gather.conf
acct_gather.confから構成オプションを設定する

Arguments:
tbl -- hash table of options./span>

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

void acct_gather_profile_g_conf_get(s_p_hashtbl_t *tbl)

Description:
Gets configuration options from acct_gather.conf
acct_gather.confから構成オプションを取得します

Returns:
void* pointer to slurm_acct_gather_conf_t on success, or
NULL on failure.

int acct_gather_profile_p_node_step_start(stepd_step_rec_t* job)

Description:
Called once per step on each node from slurmstepd, before launching tasks.
タスクを起動する前に、slurmstepdから各ノードでステップごとに1回呼び出されます。

Provides an opportunity to create files and other node-step level initialization.
ファイルおよびその他のノードステップレベルの初期化を作成する機会を提供します。

Arguments:
job -- slumd_job_t structure containing information about the step.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int acct_gather_profile_p_node_step_end(stepd_step_rec_t* job)

Description:
Called once per step on each node from slurmstepd, after all tasks end.
すべてのタスクが終了した後、slurmstepdから各ノードでステップごとに1回呼び出されます。

Provides an opportunity to close files, etc.
ファイルなどを閉じる機会を提供します。

Arguments:
job -- slumd_job_t structure containing information about the step.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int acct_gather_profile_p_task_start(stepd_step_rec_t* job, uint32_t taskid)

Description:
Called once per task from slurmstepd, BEFORE node step start is called.
slurmstepdからタスクごとに1回呼び出され、BEFOREノードステップ開始が呼び出されます。

Provides an opportunity to gather beginning values from node counters (bytes_read ...)
ノードカウンター（bytes_read ...）から開始値を収集する機会を提供します

Arguments:
job -- slumd_job_t structure containing information about the step.
taskid -- Slurm taskid.

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int acct_gather_profile_p_task_end(stepd_step_rec_t* job, pid_t taskpid)

Description:
Called once per task from slurmstepd.
slurmstepdからタスクごとに1回呼び出されます。

Provides an opportunity to put final data for a task.
タスクの最終データを配置する機会を提供します。

Arguments:
job -- slumd_job_t structure containing information about the step.
pid -- task process id (pid_t).

Returns:
SLURM_SUCCESS on success, or
SLURM_ERROR on failure.

int acct_gather_profile_p_add_sample_data(uint32_t type, void* data);

Description:
Put data at the Node Samples level. Typically called from something called at either job_acct_gather interval or acct_gather_energy interval.
ノードサンプルレベルでデータを配置します。通常、job_acct_gather間隔またはacct_gather_energy間隔で呼び出されたものから呼び出されます。

All samples in the same group will eventually be consolidated in one time series.
同じグループのすべてのサンプルは、最終的に1つの時系列に統合されます。

Arguments:

type -- identifies the type of data.
data -- data structure to be put to the file.

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 node profile data.
これらのパラメーターをslurm.confで使用して、ノードプロファイルデータを収集するプラグインと頻度を構成できます。

AcctGatherProfileType

Specifies which plugin should be used.
使用するプラグインを指定します。

The acct_gather.conf provides profile configuration options.
acct_gather.confは、プロファイル構成オプションを提供します。

ProfileDir

Path to location in a shared file system in which to write profile data. There is no default as there is no standard location for a shared file system. It this parameter is not specified, no profiling will occur.
プロファイルデータを書き込む共有ファイルシステム内の場所へのパス。共有ファイルシステムには標準の場所がないため、デフォルトはありません。このパラメーターが指定されていない場合、プロファイリングは行われません。

ProfileDefaultProfile

Default setting for --profile command line option for srun, salloc, sbatch.
srun、salloc、sbatchの--profileコマンドラインオプションのデフォルト設定。

The default profile value is none which means no profiling will be done for jobs. The hdf5 plugin also includes;
デフォルトのプロファイル値はnoneです。つまり、ジョブのプロファイリングは行われません。hdf5プラグインにも含まれています。

• energy sample energy use for the node.
  ノードのエネルギーサンプルのエネルギー使用量。
  
• lustre sample i/o to the Lustre file system for the node.
  ノードのLusterファイルシステムへのサンプルI / Oの光沢。
  
• network sample i/o through the network (interconnect) interface for the node.
  ノードのネットワーク（相互接続）インターフェースを介したネットワークサンプル入出力。
  
• task sample local disk I/O, cpu and memory use for each task.
  タスクサンプルごとのローカルディスクI / O、CPU、メモリ使用量。
  
• all all of the above.
  上記のすべてのすべて。
  

Use caution when setting the default to values other than none as a file for each job will be created. This option is provided for test systems.
各ジョブのファイルが作成されるため、デフォルトをnone以外の値に設定するときは注意してください。このオプションは、テストシステム用に提供されています。

Most of the sources of profile data are associated with various acct_gather plugins. The acct_gather.conf file has setting for various sampling mechanisms that can be used to change the frequency at which samples occur.
プロファイルデータのソースのほとんどは、さまざまなacct_gatherプラグインに関連付けられています。acct_gather.confファイルには、サンプルが発生する頻度を変更するために使用できるさまざまなサンプリングメカニズムの設定があります。

Data Types

A plugin-like structure is implemented to generalize HDF5 data operations from various sources. A C typedef is defined for each datatype. These declarations are in /common/slurm_acct_gather_profile.h so the datatype are common to all profile plugins.
プラグインのような構造が実装され、さまざまなソースからのHDF5データ操作が一般化されます。Cのtypedefは、データ型ごとに定義されます。これらの宣言は/common/slurm_acct_gather_profile.hにあるため、データ型はすべてのプロファイルプラグインに共通です。

The operations are defined via structures of function pointers, and they are defined in /plugins/acct_gather_profile/common/profile_hdf5.h and should work on any HDF5 implementation, not only hdf5.
操作は関数ポインターの構造を介して定義され、/ plugins / acct_gather_profile / common / profile_hdf5.hで定義され、hdf5だけでなく任意のHDF5実装で機能するはずです。

Functions must be implemented to perform various operations for the datatype. The api for the plugin includes an argument for the datatype so that the implementation of that api can call the specific operation for that datatype.
データ型のさまざまな操作を実行するには、関数を実装する必要があります。プラグインのAPIにはデータ型の引数が含まれているため、そのAPIの実装はそのデータ型の特定の操作を呼び出すことができます。

Groups in the HDF5 file containing a dataset will include an attribute for the datatype so that the program that merges step files into the job can discover the type of the group and do the right thing.
データセットを含むHDF5ファイル内のグループには、データ型の属性が含まれるため、ステップファイルをジョブにマージするプログラムは、グループのタイプを検出して正しいことを実行できます。

For example, the typedef for the energy sample datatype;
たとえば、エネルギーサンプルデータ型のtypedef。

typedef struct profile_energy {
    char     tod[TOD_LEN];	// Not used in node-step
    time_t   time;
    uint64_t watts;
    uint64_t cpu_freq;
} profile_energy_t;

A factory method is implemented for each type to construct a structure with functions implementing various operations for the type. The following structure of functions is required for each type.
ファクトリメソッドは、型ごとに実装され、型のさまざまな操作を実装する関数を持つ構造を構築します。タイプごとに次の関数構造が必要です。

/*
 * Structure of function pointers of common operations on a
 * profile data type. (Some may be stubs, particularly if the data type
 * does not represent a time series.
 *	dataset_size -- size of one dataset (structure size).
 *      create_memory_datatype -- creates hdf5 memory datatype
 *          corresponding to the datatype structure.
 *      create_file_datatype -- creates hdf5 file datatype
 *          corresponding to the datatype structure.
 *      create_s_memory_datatype -- creates hdf5 memory datatype
 *          corresponding to the summary datatype structure.
 *      create_s_file_datatype -- creates hdf5 file datatype
 *          corresponding to the summary datatype structure.
 *      init_job_series -- allocates a buffer for a complete time
 *          series (in job merge) and initializes each member
 *      merge_step_series -- merges all the individual time samples
 *          into a single data set with one item per sample.
 *          Data items can be scaled (e.g. subtracting beginning time)
 *          differenced (to show counts in interval) or other things
 *          appropriate for the series.
 *      series_total -- accumulate or average members in the entire
 *          series to be added to the file as totals for the node or
 *          task.
 *      extract_series -- format members of a structure for putting
 *          to a file data extracted from a time series to be imported into
 *          another analysis tool. (e.g. format as comma separated value.)
 *      extract_totals -- format members of a structure for putting
 *          to a file data extracted from a time series total to be imported
 *          into another analysis tool. (e.g. format as comma,separated value.)
 */
typedef struct profile_hdf5_ops {
    int   (*dataset_size) ();
    hid_t (*create_memory_datatype) ();
    hid_t (*create_file_datatype) ();
    hid_t (*create_s_memory_datatype) ();
    hid_t (*create_s_file_datatype) ();
    void* (*init_job_series) (int, int);
    void  (*merge_step_series) (hid_t, void*, void*, void*);
    void* (*series_total) (int, void*);
    void  (*extract_series) (FILE*, bool, int, int, char*,
				       char*, void*);
    void  (*extract_totals) (FILE*, bool, int, int, char*,
				       char*, void*);
} profile_hdf5_ops_t;

Note there are two different data types for supporting time series.
時系列をサポートするために2つの異なるデータ型があることに注意してください。

1) A primary type is defined for gathering data in the node step file. It is typically named profile_{series_name}_t.
1）ノードステップファイルでデータを収集するためにプライマリタイプが定義されています。通常、profile_ {series_name} _tという名前です。

2) Another type is defined for summarizing series totals. It is typically named profile_{series_name}_s_t. It does not have a 'factory'. It is only used in the functions of the primary data type and the primaries structure has operations to create appropriate hdf5 objects.
2）シリーズ合計を要約するために、別のタイプが定義されています。通常、profile_ {series_name} _s_tという名前です。「工場」はありません。プライマリデータ型の関数でのみ使用され、primaries構造には適切なhdf5オブジェクトを作成する操作があります。

When adding a new type, the profile_factory function has to be modified to return an ops for the type.
新しいタイプを追加する場合、そのタイプの操作を返すようにprofile_factory関数を変更する必要があります。

Interaction between type and hdf5.
タイプとhdf5の間の相互作用。

• The profile_{type}_t structure is used by callers of the add_sample_data functions.
  profile_ {type} _t構造体は、add_sample_data関数の呼び出し元によって使用されます。
  
• HDF5 needs a memory_datatype to transform this structure into its dataset object in memory. The create_memory_datatype function creates the appropriate object.
  HDF5では、この構造をメモリ内のデータセットオブジェクトに変換するために、memory_datatypeが必要です。create_memory_datatype関数は、適切なオブジェクトを作成します。
  
• HDF5 needs a file_datatype to transform the dataset into how it will be written to the HDF5 file (or to transform what it reads from a file into a dataset.) The create_file_datatype function creates the appropriate object.
  HDF5では、データセットをHDF5ファイルへの書き込み方法に変換する（またはファイルから読み取ったデータセットをデータセットに変換する）ためにfile_datatypeが必要です。create_file_datatype関数は適切なオブジェクトを作成します。
  

Last modified 27 March 2015