Slurm Profile Accounting Plugin API (AcctGatherProfileType)

Overview

This document describes Slurm profile accounting plugins and the API that defines them.
このドキュメントでは、Slurmプロファイルアカウンティングプラグインとそれらを定義するAPIについて説明します。
It is intended as a resource to programmers wishing to write their own Slurm profile accounting plugins.
これは、独自の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.
別のユーザーガイドには、プラグインのhdf5バージョンの使用方法が記載されています。
An influxdb plugin is also available since Slurm 17.11.
Influxdbプラグインは、Slurm17.11以降でも使用できます。

The plugin provides an API for making calls to store data at various points in a step's lifecycle.
プラグインは、ステップのライフサイクルのさまざまな時点でデータを格納するための呼び出しを行うためのAPIを提供します。
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.
定期的なサンプルは、最終的に、ジョブのノードごとに1つの時系列データセットに統合されます。

The plugin's primary work is done within slurmstepd on the compute nodes.
プラグインの主な作業は、計算ノードのslurmstepd内で行われます。
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.
データは通常、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カウント、Lustre並列ファイルシステムからのノードからのI / Oカウント、ディスクI / Oカウント、各タスクのcpuとメモリ使用率、およびエネルギー使用。

The hdf5 implementation stores this data in a HDF5 file for each step on each node for the jobs.
hdf5実装は、ジョブの各ノードの各ステップのHDF5ファイルにこのデータを格納します。
A separate program (sh5util) is provided to consolidate all the node-step files in one container for the job.
すべてのノードステップファイルをジョブの1つのコンテナに統合するために、別のプログラム（sh5util）が提供されています。
HDF5 is a well known structured data set that allows different types of related data to be stored in one file.
HDF5は、さまざまなタイプの関連データを1つのファイルに保存できるようにするよく知られた構造化データセットです。
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.
これらのファイルを表示および操作するためのコモディティプログラム、特にHDF5Viewがあります。
sh5util also provides some capability for extracting subsets of date for import into other analysis tools like spreadsheets.
sh5utilは、スプレッドシートなどの他の分析ツールにインポートするために、日付のサブセットを抽出するためのいくつかの機能も提供します。

This plugin is incompatible with --enable-front-end.
このプラグインは--enable-front-endと互換性がありません。
It you need to simulate a large configuration, please use --enable-multiple-slurmd.
大規模な構成をシミュレートする必要がある場合は、-enable-multiple-slurmdを使用してください。

Slurm profile accounting plugins must conform to the Slurm Plugin API with the following specifications:
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.
メジャータイプは「acct_gather_profile」である必要があります。マイナータイプは、プロファイルアカウンティングのタイプに適した任意の名前にすることができます。
We currently use
現在使用しています

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

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.
注：これらのinitおよびfini関数は、dlopen（3）システムライブラリで説明されているものと同じではありません。
The C run-time system co-opts those symbols for its own initialization.
Cランタイムシステムは、独自の初期化のためにこれらのシンボルを採用します。
The system _init() is called before the Slurm init(), and the Slurm fini() is called before the system's _fini().
システム_init（）はSlurm init（）の前に呼び出され、Slurm fini（）はシステムの_fini（）の前に呼び出されます。

void acct_gather_profile_g_conf_options(void)

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

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回呼び出され、ノードステップ開始の前に呼び出されます。

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.
デフォルトのプロファイル値はnoneです。これは、ジョブのプロファイリングが行われないことを意味します。
The hdf5 plugin also includes;
hdf5プラグインには以下も含まれます。

• energy sample energy use for the node.
  ノードのエネルギーサンプルエネルギー使用。
  
• lustre sample i/o to the Lustre file system for the node.
  ノードのLustreファイルシステムへのLustreサンプルI / O。
  
• network sample i/o through the network (interconnect) interface for the node.
  ノードのネットワーク（相互接続）インターフェースを介したネットワークサンプルI / O。
  
• 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.
各ジョブのファイルが作成されるため、デフォルトをnone以外の値に設定する場合は注意が必要です。
This option is provided for test systems.
このオプションは、テストシステム用に提供されています。

Most of the sources of profile data are associated with various acct_gather plugins.
プロファイルデータのソースのほとんどは、さまざまなacct_gatherプラグインに関連付けられています。
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.confファイルには、サンプルが発生する頻度を変更するために使用できるさまざまなサンプリングメカニズムの設定があります。

Data Types

A plugin-like structure is implemented to generalize HDF5 data operations from various sources.
プラグインのような構造は、さまざまなソースからのHDF5データ操作を一般化するために実装されています。
A C typedef is defined for each datatype.
AC typedefは、データ型ごとに定義されています。
These declarations are in /common/slurm_acct_gather_profile.h so the datatype are common to all profile plugins.
これらの宣言は/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.
1）ノードステップファイルにデータを収集するためのプライマリタイプが定義されています。
It is typically named profile_{series_name}_t.
通常、profile_ {series_name} _tという名前です。

2) Another type is defined for summarizing series totals.
2）シリーズの合計を要約するために別のタイプが定義されています。
It is typically named profile_{series_name}_s_t.
通常、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.
これはプライマリデータ型の関数でのみ使用され、プライマリ構造には適切なhdf5オブジェクトを作成する操作があります。

When adding a new type, the profile_factory function has to be modified to return an ops for the type.
新しいタイプを追加するときは、そのタイプのopsを返すように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.
  HDF5は、この構造をメモリ内のデータセットオブジェクトに変換するために、memory_datatypeを必要とします。
  The create_memory_datatype function creates the appropriate object.
  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.)
  HDF5は、データセットをHDF5ファイルへの書き込み方法に変換する（またはファイルから読み取ったものをデータセットに変換する）ためにfile_datatypeを必要とします。
  The create_file_datatype function creates the appropriate object.
  create_file_datatype関数は、適切なオブジェクトを作成します。
  

Last modified 27 March 2015