Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Provide access to resource usage for processes and nodes #335

Open
wants to merge 1 commit into
base: v4
Choose a base branch
from
Open

Provide access to resource usage for processes and nodes #335

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
278 changes: 278 additions & 0 deletions Chap_API_Job_Mgmt.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1167,3 +1167,281 @@ \subsection{Log attributes}
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Resource Usage}
\label{api:resusage}

Applications and tools often want to obtain a snapshot of the resources utilized by individual
processes and/or nodes in their job. \ac{PMIx} provides attributes for querying such information
and accompanying structures for the results.

\subsection{Process statistics}
\label{api:pstats:struct}

The process statistics structure contains information available from many \acp{OS}. The field
corresponding to any information that is not available will be set to zero.

\declarestruct{pmix_proc_stats_t}

\versionMarker{4.1}
\cspecificstart
\begin{codepar}
typedef struct pmix_proc_stats \{
/* process ident info */
char *node;
pmix_proc_t proc;
pid_t pid;
char *cmd;
/* process stats */
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have a link to more descriptions on each of these stats? We take them from Linux so a pointer to a good manpage description would be helpful to someone new to these fields.

char state[2];
struct timeval time;
float percent_cpu;
int32_t priority;
uint16_t num_threads;
float pss; /* in MBytes */
float vsize; /* in MBytes */
float rss; /* in MBytes */
float peak_vsize; /* in MBytes */
uint16_t processor;
/* time at which sample was taken */
struct timeval sample_time;
\} pmix_proc_stats_t;
\end{codepar}
\cspecificend

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Process statistics support macros}
The following macros are provided to support the \refstruct{pmix_proc_stats_t} structure.

\littleheader{Initialize the proc stats structure}
\declaremacro{PMIX_PROC_STATS_CONSTRUCT}

Initialize the \refstruct{pmix_proc_stats_t} fields.

\versionMarker{4.1}
\cspecificstart
\begin{codepar}
PMIX_PROC_STATS_CONSTRUCT(m)
\end{codepar}
\cspecificend

\begin{arglist}
\argin{m}{Pointer to the structure to be initialized (pointer to \refstruct{pmix_proc_stats_t})}
\end{arglist}

\littleheader{Destruct the proc stats structure}
\declaremacro{PMIX_PROC_STATS_DESTRUCT}

Destruct the \refstruct{pmix_proc_stats_t} fields.

\versionMarker{4.1}
\cspecificstart
\begin{codepar}
PMIX_PROC_STATS_DESTRUCT(m)
\end{codepar}
\cspecificend

\begin{arglist}
\argin{m}{Pointer to the structure to be destructed (pointer to \refstruct{pmix_proc_stats_t})}
\end{arglist}

\littleheader{Create a proc stats array}
\declaremacro{PMIX_PROC_STATS_CREATE}

Allocate and initialize an array of \refstruct{pmix_proc_stats_t} structures.

\versionMarker{4.1}
\cspecificstart
\begin{codepar}
PMIX_PROC_STATS_CREATE(m, n)
\end{codepar}
\cspecificend

\begin{arglist}
\arginout{m}{Address where the pointer to the array of \refstruct{pmix_proc_stats_t} structures shall be stored (handle)}
\argin{n}{Number of structures to be allocated (\code{size_t})}
\end{arglist}


\littleheader{Free a proc stats structure}
\declaremacro{PMIX_PROC_STATS_RELEASE}

Release a \refstruct{pmix_proc_stats_t} structure.

\versionMarker{4.1}
\cspecificstart
\begin{codepar}
PMIX_PROC_STATS_RELEASE(m)
\end{codepar}
\cspecificend

\begin{arglist}
\argin{m}{Pointer to a \refstruct{pmix_proc_stats_t} structure (handle)}
\end{arglist}

\littleheader{Free a proc stats array}
\declaremacro{PMIX_PROC_STATS_FREE}

Release an array of \refstruct{pmix_proc_stats_t} structures.

\versionMarker{4.1}
\cspecificstart
\begin{codepar}
PMIX_PROC_STATS_FREE(m, n)
\end{codepar}
\cspecificend

\begin{arglist}
\argin{m}{Pointer to the array of \refstruct{pmix_proc_stats_t} structures (handle)}
\argin{n}{Number of structures in the array (\code{size_t})}
\end{arglist}

\subsection{Process statistics attributes}
\label{api:pstats:attrs}

The following attributes can be used to query for process statistics:

\declareAttributeNEW{PMIX_PROC_RESOURCE_USAGE}{"pmix.pstats"}{pmix_proc_t}{
Return the resource usage statistics for the specified process in a \refstruct{pmix_proc_stats_t} structure.
If a namespace is combined with
\refconst{PMIX_RANK_WILDCARD}, then results for all processes in the given job
will be returned in a \refstruct{pmix_data_array_t} of \refstruct{pmix_proc_stats_t} structures.
This attribute can be used with
qualifiers such as \refattr{PMIX_SESSION_ID} to identify the session of the namespace whose
statistics are being requested.
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Node statistics}
\label{api:ndstats:struct}

The node statistics structure contains information available from many \acp{OS}. The field
corresponding to any information that is not available will be set to zero. Note that the
resource usage reported in the node statistics is an aggregate of all activity on the node
and not just activity associated with the caller's job.

\declarestruct{pmix_node_stats_t}

\versionMarker{4.1}
\cspecificstart
\begin{codepar}
typedef struct pmix_node_stats \{
char *node;
/* node-level load averages */
float la;
float la5;
float la15;
/* memory usage */
float total_mem; /* in MBytes */
float free_mem; /* in MBytes */
float buffers; /* in MBytes */
float cached; /* in MBytes */
float swap_cached; /* in MBytes */
float swap_total; /* in MBytes */
float swap_free; /* in MBytes */
float mapped; /* in MBytes */
/* time at which sample was taken */
struct timeval sample_time;
\} pmix_node_stats_t;
\end{codepar}
\cspecificend

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Node statistics support macros}
The following macros are provided to support the \refstruct{pmix_node_stats_t} structure.

\littleheader{Initialize the node stats structure}
\declaremacro{PMIX_NODE_STATS_CONSTRUCT}

Initialize the \refstruct{pmix_node_stats_t} fields.

\versionMarker{4.1}
\cspecificstart
\begin{codepar}
PMIX_NODE_STATS_CONSTRUCT(m)
\end{codepar}
\cspecificend

\begin{arglist}
\argin{m}{Pointer to the structure to be initialized (pointer to \refstruct{pmix_node_stats_t})}
\end{arglist}

\littleheader{Destruct the node stats structure}
\declaremacro{PMIX_NODE_STATS_DESTRUCT}

Destruct the \refstruct{pmix_node_stats_t} fields.

\versionMarker{4.1}
\cspecificstart
\begin{codepar}
PMIX_NODE_STATS_DESTRUCT(m)
\end{codepar}
\cspecificend

\begin{arglist}
\argin{m}{Pointer to the structure to be destructed (pointer to \refstruct{pmix_node_stats_t})}
\end{arglist}

\littleheader{Create a node stats array}
\declaremacro{PMIX_NODE_STATS_CREATE}

Allocate and initialize an array of \refstruct{pmix_node_stats_t} structures.

\versionMarker{4.1}
\cspecificstart
\begin{codepar}
PMIX_NODE_STATS_CREATE(m, n)
\end{codepar}
\cspecificend

\begin{arglist}
\arginout{m}{Address where the pointer to the array of \refstruct{pmix_node_stats_t} structures shall be stored (handle)}
\argin{n}{Number of structures to be allocated (\code{size_t})}
\end{arglist}


\littleheader{Free a node stats structure}
\declaremacro{PMIX_NODE_STATS_RELEASE}

Release a \refstruct{pmix_node_stats_t} structure.

\versionMarker{4.1}
\cspecificstart
\begin{codepar}
PMIX_NODE_STATS_RELEASE(m)
\end{codepar}
\cspecificend

\begin{arglist}
\argin{m}{Pointer to a \refstruct{pmix_node_stats_t} structure (handle)}
\end{arglist}

\littleheader{Free a node stats array}
\declaremacro{PMIX_NODE_STATS_FREE}

Release an array of \refstruct{pmix_node_stats_t} structures.

\versionMarker{4.1}
\cspecificstart
\begin{codepar}
PMIX_NODE_STATS_FREE(m, n)
\end{codepar}
\cspecificend

\begin{arglist}
\argin{m}{Pointer to the array of \refstruct{pmix_node_stats_t} structures (handle)}
\argin{n}{Number of structures in the array (\code{size_t})}
\end{arglist}

\subsection{Node statistics attributes}
\label{api:ndstats:attrs}

The following attributes can be used to query for node statistics:

\declareAttributeNEW{PMIX_NODE_RESOURCE_USAGE}{"pmix.ndstats"}{char*}{
Return the resource usage statistics for the specified node in a \refstruct{pmix_node_stats_t} structure.
If no node is specified, then
results for all nodes hosting processes within the job of the requestor
will be returned in a \refstruct{pmix_data_array_t} of \refstruct{pmix_node_stats_t} structures.
}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similar to the PMIX_PROC_RESOURCE_USAGE should we point out that:

This attribute can be used with qualifiers such as \refattr{PMIX_SESSION_ID} to identify the session of the namespace whose statistics are being requested.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
7 changes: 7 additions & 0 deletions Chap_API_Struct.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -497,6 +497,7 @@ \subsubsection{Process structure support macros}

Destruct the \refstruct{pmix_proc_t} fields.

\versionMarker{1.0}
\cspecificstart
\begin{codepar}
PMIX_PROC_DESTRUCT(m)
Expand Down Expand Up @@ -2324,6 +2325,12 @@ \section{Generalized Data Types Used for Packing/Unpacking}
Values above this are guaranteed not to conflict with \ac{PMIx} values.
Definitions should always be based on the \refconst{PMIX_DATA_TYPE_MAX} constant and not a specific value as the value of the constant may change.
%
\declareconstitemNEW{PMIX_PROC_STATS}
Structure containing process resource usage statistics (\refstruct{pmix_proc_stats_t})
%
\declareconstitemNEW{PMIX_NODE_STATS}
Structure containing node resource usage statistics (\refstruct{pmix_node_stats_t})
%
\end{constantdesc}


Expand Down
2 changes: 2 additions & 0 deletions Chap_API_Sync_Access.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -561,6 +561,8 @@ \subsection{\code{PMIx_Query_info}}
\pasteAttributeItem{PMIX_QUERY_AUTHORIZATIONS}
\pasteAttributeItem{PMIX_PROC_PID}
\pasteAttributeItem{PMIX_PROC_STATE_STATUS}
\pasteAttributeItem{PMIX_PROC_RESOURCE_USAGE}
\pasteAttributeItem{PMIX_NODE_RESOURCE_USAGE}

\optattrend

Expand Down