doc/HostAdmin/FS/EPTF CLL Host Admin, Function Description.adoc - titan/titan.Libraries.CLL - Git at Google

 ---
 Author: Gábor Tatárka
 Version: 20/155 16-CNL 113 512, Rev. D
 Date: 2011-12-06

 ---
 = EPTF CLL Host Admin, Function Description
 :author: Gábor Tatárka
 :revnumber: 20/155 16-CNL 113 512, Rev. D
 :revdate: 2011-12-06
 :toc:

 == How to Read This Document

 This is the Function Description for the Host Admin of the Ericsson Performance Test Framework (TitanSim), Core Load Library (CLL). TitanSim CLL is developed for the TTCN-3 <<_1, [1]>> Toolset with TITAN <<_2, [2]>>.

 == Scope

 This document is to specify the content and functionality of the Host Admin feature of the TitanSim CLL.

 == Recommended Way of Reading

 The readers are supposed to get familiar with the concept and functionalities of TitanSim CLL <<_3, [3]>>. They should get familiar with the list of abbreviations and the glossary.

 = General Description

 The aim of the EPTF CLL Host Admin feature is to provide processor and memory usage measurement for a given host it is started on. Supported platforms are Solaris 5.6 and 5.8, Linux and Win32/Cygwin.

 This document specifies the Host Admin feature of the TitanSim CLL.

 The EPTF Host Admin feature makes it possible to

 * Measure average processor load of the host it is started on
 * Query the number of processors
 * Measure per-processor load
 * Query the physical memory size
 * Get the amount of free (available) memory
 * Monitor the CPU load and memory usage of processes

 The Host Admin feature is divided in two parts: Host Admin Base and Host Admin. The former provides local measurements for components that extend it, and the latter provides remote measurements through the EPTF Variables <<_5, [5]>> (or a local measurement interface running in a separate component).

 To be able to use EPTF CLL Host Admin Base, the user component should extend the `EPTF_HostAdmin_Base_CT` component.

 To be able to use the EPTF CLL Host Admin, a new component of type `EPTF_HostAdmin_CT` should be created and the function `f_EPTF_HostAdmin_behavior()` should be started on it. The measurement data can be accessed by subscribing to the respective EPTF variables.

 == Host Admin Server

 There is an additional component called Host Admin Server as a sub-feature of Host Admin. This component periodically queries the running EPTF processes from the Base feature. If it finds a process that was started on a new host, it automatically starts a Host Admin component on that host. Host and process statistics are collected from the started Host Admins by the server and provided as data sources/Variables.

 The process statistics that are collected by the Host Admin Server are only for EPTF components. These can be displayed on the GUI per host, sorted either by name, CPU load or memory usage. Statistics are also available by the `selfName` parameter of the EPTF processes. An example use-case can be seen in the demo of the feature.

 = Functional Interface

 Apart from this description a cross-linked reference guide for the TitanSim CLL Functions can be reached for on-line reading <<_4, [4]>>.

 == Naming Conventions

 All functions in Host Admin Base have the prefix `f_EPTF_HostAdmin_Base`.

 All functions in Host Admin have the prefix `f_EPTF_HostAdmin`.

 == Host Admin Base Public Functions

 === Initialization
 Before using the EPTF Host Admin Base feature the

 `f_EPTF_HostAdmin_Base_InitMeasInterface()`

 function should be called. This initializes the EPTF Host Admin Base feature.

 === Cleanup

 The function `f_EPTF_HostAdmin_Base_CleanupMeasInterface()` should be called before stopping the component.

 === Updating Masurement Data

 The function `f_EPTF_HostAdmin_Base_update()` can be used to update the measurement data stored as component variables in the component `EPTF_HostAdmin_Base_CT`.

 === Get the Name of a Process

 The function `f_EPTF_HostAdmin_Base_getProcessName()` function returns the name (command) of a process by its PID.

 === Add Process Statistics

 The function `f_EPTF_HostAdmin_Base_addProcessStat()` function can be used to start measurement of CPU and memory usage of a process. The PID of the process has to be passed in as a parameter. The function returns the internal index of the process statistics.

 === Remove Process Statistics

 The function `f_EPTF_HostAdmin_Base_removeProcessStat()` function can be used to remove process statistics previously added by `f_EPTF_HostAdmin_Base_addProcessStat`, with the PID of the process as the input parameter.

 The function `f_EPTF_HostAdmin_Base_removeProcessStatByIdx()` function is the same as `f_EPTF_HostAdmin_Base_removeProcessStat`, but the statistics index (as returned by `f_EPTF_HostAdmin_Base_addProcessStat`) has to be specified instead of the PID.

 === Get CPU Load of a Process

 The function `f_EPTF_HostAdmin_Base_getProcessCpuLoad()` and `f_EPTF_HostAdmin_Base_getProcessCpuLoadByIdx()` can be used to get the CPU load of a process by its PID or statistics index respectively.

 === Get Memory Usage of a Process

 The function `f_EPTF_HostAdmin_Base_getProcessMemUsage()` and `f_EPTF_HostAdmin_Base_getProcessMemUsageByIdx()` can be used to get the memory usage of a process.

 == Host Admin Public Functions

 === Behavior Function

 The following function should be started on the EPTF Host Admin component:

 `f_EPTF_HostAdmin_behavior(pl_selfName)`

 This function automatically initializes the Host Admin component and periodically updates the measurement variables and dependent EPTF Variables.

 == Host Admin Server Public Functions

 [[initialization-0]]
 === Initialization
 Before using the EPTF Host Admin Server feature the

 `f_EPTF_HostAdminServer_init_CT(pl_selfName, pl_dataSource_compRef)`

 function should be called. This initializes the EPTF Host Admin Base feature.

 === Setting the Sort Order

 The sort order of process statistics can be set with the following function:

 `f_EPTF_HostAdminServer_setSortBy(pl_sortBy)`

 === Getting Variable Name Prefix for Process Stats
 The function

 `f_EPTF_HostAdminServer_getProcessVarNamePrefix(pl_processSelfName)`

 can be used to get a variable name prefix for process statistics by the EPTF `selfName` of a process.

 Currently, the following constants are defined for variable name suffixes:

 * `c_HostAdminServer_dataElementHostName`: the host name of the process, type: charstring.
 * `c_HostAdminServer_dataElementPID`: process id, type: integer.
 * `c_HostAdminServer_dataElementCpuLoad`: CPU load, type: float.
 * `c_HostAdminServer_dataElementMemUsage`: memory usage in kilobytes, type: integer.
 * `c_HostAdminServer_dataElementMemUsageHRF`: memory usage in human readable format, type: charstring.

 For example, the Variable name for the CPU usage statistics of EPTF component with `selfName` "SIPLGen2" can be get with the following:

 `f_EPTF_HostAdminServer_getProcessVarNamePrefix("IPLGen2") & c_HostAdminServer_dataElementCpuLoad`

 == Summary Table of All Public Functions for EPTF Host Admin

 See Summary of Host Admin functions below:

 [width="100%",cols="50%,50%",options="header",]
 |==========================================================================================================
 |Function name |Description
 |`f_EPTF_HostAdmin_Base_InitMeasInterface` |Initializes the Host Admin Base Component
 |`f_EPTF_HostAdmin_Base_CleanupMeasInterface` |Should be called before stopping the Host Admin Base component
 |`f_EPTF_HostAdmin_Base_update` |Updates measurement data
 |`f_EPTF_HostAdmin_Base_getProcessName` |Get the name of a process by PID
 |`f_EPTF_HostAdmin_Base_addProcessStat` |Add process statistics by PID
 |`f_EPTF_HostAdmin_Base_removeProcessStat` |Remove process statistics by PID
 |`f_EPTF_HostAdmin_Base_removeProcessStatByIdx` |Remove process statistics by index
 |`f_EPTF_HostAdmin_Base_getProcessCpuLoad` |Get CPU load of process by PID
 |`f_EPTF_HostAdmin_Base_getProcessCpuLoadByIdx` |Get CPU load of process by index
 |`f_EPTF_HostAdmin_Base_getProcessMemUsage` |Get memory usage of process by PID
 |`f_EPTF_HostAdmin_Base_getProcessMemUsageByIdx` |Get memory usage of process by index
 |`f_EPTF_HostAdmin_behavior` |Behavior function that should be started on Host Admin component
 |`f_EPTF_HostAdminServer_init_CT` |Initilize Host Admin Server
 |`f_EPTF_HostAdminServer_setSortBy` |Set the sort order for pre host process statistics
 |`f_EPTF_HostAdminServer_getProcessVarNamePrefix` |Get Variable name prefix for process stats by `selfName`
 |==========================================================================================================

 == `DataSource` Client Functionality

 The Host Admin feature provides `DataSourceClient` functionality. This means that a `HostAdmin` component has several Variables, that are available to use with the help of a `DataSource` server, for example the `UIHandler`. With the call of the function `f_EPTF_UIHandler_createGUI()`, a custom GUI is built, and the data of the features are freely to use. For more info about the `DataSource` feature, see the `UIHandler` Function Description <<_6, [7]>>. For the list of the existing iterators and external data elements, see the natural documentation.

 = Terminology

 *TitanSim Core (Load) Library(CLL):* +
 It is that part of the TitanSim software that is totally project independent. (I.e., which is not protocol-, or application-dependent). The TitanSim CLL is to be supplied and supported by the TCC organization. Any TitanSim CLL development is to be funded centrally by Ericsson.

 *EPTF Variable:* +
 An enhanced component variable that makes it possible to access the values of other Variables in remote components.

 = Abbreviations

 CLL:: Core Load Library

 EPTF:: Ericsson Load Test Framework, formerly TITAN Load Test Framework

 MTC:: Main Test Component

 TitanSim:: Ericsson Load Test Framework, formerly TITAN Load Test Framework

 TTCN-3:: Testing and Test Control Notation version 3 <<_1, [1]>>

 = References

 [[_1]]
 [1] ETSI ES 201 873-1 v3.2.1 (2007-02) +
 The Testing and Test Control Notation version 3. Part 1: Core Language

 [[_2]]
 [2] User Guide for the TITAN TTCN-3 Test Executor

 [[_3]]
 [3] TitanSim CLL for TTCN-3 toolset with TITAN, Function Specification

 [[_4]]
 [4] TitanSim CLL for TTCN-3 toolset with TITAN +
 http://ttcn.ericsson.se/products/libraries.shtml[Reference Guide]

 [[_5]]
 [5] EPTF CLL Variable, Function Description

 [[_6]]
 [6] EPTF CLL UIHandler, Function Description
	---
	Author: Gábor Tatárka
	Version: 20/155 16-CNL 113 512, Rev. D
	Date: 2011-12-06

	---
	= EPTF CLL Host Admin, Function Description
	:author: Gábor Tatárka
	:revnumber: 20/155 16-CNL 113 512, Rev. D
	:revdate: 2011-12-06
	:toc:

	== How to Read This Document

	This is the Function Description for the Host Admin of the Ericsson Performance Test Framework (TitanSim), Core Load Library (CLL). TitanSim CLL is developed for the TTCN-3 <<_1, [1]>> Toolset with TITAN <<_2, [2]>>.

	== Scope

	This document is to specify the content and functionality of the Host Admin feature of the TitanSim CLL.

	== Recommended Way of Reading

	The readers are supposed to get familiar with the concept and functionalities of TitanSim CLL <<_3, [3]>>. They should get familiar with the list of abbreviations and the glossary.

	= General Description

	The aim of the EPTF CLL Host Admin feature is to provide processor and memory usage measurement for a given host it is started on. Supported platforms are Solaris 5.6 and 5.8, Linux and Win32/Cygwin.

	This document specifies the Host Admin feature of the TitanSim CLL.

	The EPTF Host Admin feature makes it possible to

	* Measure average processor load of the host it is started on
	* Query the number of processors
	* Measure per-processor load
	* Query the physical memory size
	* Get the amount of free (available) memory
	* Monitor the CPU load and memory usage of processes

	The Host Admin feature is divided in two parts: Host Admin Base and Host Admin. The former provides local measurements for components that extend it, and the latter provides remote measurements through the EPTF Variables <<_5, [5]>> (or a local measurement interface running in a separate component).

	To be able to use EPTF CLL Host Admin Base, the user component should extend the `EPTF_HostAdmin_Base_CT` component.

	To be able to use the EPTF CLL Host Admin, a new component of type `EPTF_HostAdmin_CT` should be created and the function `f_EPTF_HostAdmin_behavior()` should be started on it. The measurement data can be accessed by subscribing to the respective EPTF variables.

	== Host Admin Server

	There is an additional component called Host Admin Server as a sub-feature of Host Admin. This component periodically queries the running EPTF processes from the Base feature. If it finds a process that was started on a new host, it automatically starts a Host Admin component on that host. Host and process statistics are collected from the started Host Admins by the server and provided as data sources/Variables.

	The process statistics that are collected by the Host Admin Server are only for EPTF components. These can be displayed on the GUI per host, sorted either by name, CPU load or memory usage. Statistics are also available by the `selfName` parameter of the EPTF processes. An example use-case can be seen in the demo of the feature.

	= Functional Interface

	Apart from this description a cross-linked reference guide for the TitanSim CLL Functions can be reached for on-line reading <<_4, [4]>>.

	== Naming Conventions

	All functions in Host Admin Base have the prefix `f_EPTF_HostAdmin_Base`.

	All functions in Host Admin have the prefix `f_EPTF_HostAdmin`.

	== Host Admin Base Public Functions

	=== Initialization
	Before using the EPTF Host Admin Base feature the

	`f_EPTF_HostAdmin_Base_InitMeasInterface()`

	function should be called. This initializes the EPTF Host Admin Base feature.

	=== Cleanup

	The function `f_EPTF_HostAdmin_Base_CleanupMeasInterface()` should be called before stopping the component.

	=== Updating Masurement Data

	The function `f_EPTF_HostAdmin_Base_update()` can be used to update the measurement data stored as component variables in the component `EPTF_HostAdmin_Base_CT`.

	=== Get the Name of a Process

	The function `f_EPTF_HostAdmin_Base_getProcessName()` function returns the name (command) of a process by its PID.

	=== Add Process Statistics

	The function `f_EPTF_HostAdmin_Base_addProcessStat()` function can be used to start measurement of CPU and memory usage of a process. The PID of the process has to be passed in as a parameter. The function returns the internal index of the process statistics.

	=== Remove Process Statistics

	The function `f_EPTF_HostAdmin_Base_removeProcessStat()` function can be used to remove process statistics previously added by `f_EPTF_HostAdmin_Base_addProcessStat`, with the PID of the process as the input parameter.

	The function `f_EPTF_HostAdmin_Base_removeProcessStatByIdx()` function is the same as `f_EPTF_HostAdmin_Base_removeProcessStat`, but the statistics index (as returned by `f_EPTF_HostAdmin_Base_addProcessStat`) has to be specified instead of the PID.

	=== Get CPU Load of a Process

	The function `f_EPTF_HostAdmin_Base_getProcessCpuLoad()` and `f_EPTF_HostAdmin_Base_getProcessCpuLoadByIdx()` can be used to get the CPU load of a process by its PID or statistics index respectively.

	=== Get Memory Usage of a Process

	The function `f_EPTF_HostAdmin_Base_getProcessMemUsage()` and `f_EPTF_HostAdmin_Base_getProcessMemUsageByIdx()` can be used to get the memory usage of a process.

	== Host Admin Public Functions

	=== Behavior Function

	The following function should be started on the EPTF Host Admin component:

	`f_EPTF_HostAdmin_behavior(pl_selfName)`

	This function automatically initializes the Host Admin component and periodically updates the measurement variables and dependent EPTF Variables.

	== Host Admin Server Public Functions

	[[initialization-0]]
	=== Initialization
	Before using the EPTF Host Admin Server feature the

	`f_EPTF_HostAdminServer_init_CT(pl_selfName, pl_dataSource_compRef)`

	function should be called. This initializes the EPTF Host Admin Base feature.

	=== Setting the Sort Order

	The sort order of process statistics can be set with the following function:

	`f_EPTF_HostAdminServer_setSortBy(pl_sortBy)`

	=== Getting Variable Name Prefix for Process Stats
	The function

	`f_EPTF_HostAdminServer_getProcessVarNamePrefix(pl_processSelfName)`

	can be used to get a variable name prefix for process statistics by the EPTF `selfName` of a process.

	Currently, the following constants are defined for variable name suffixes:

	* `c_HostAdminServer_dataElementHostName`: the host name of the process, type: charstring.
	* `c_HostAdminServer_dataElementPID`: process id, type: integer.
	* `c_HostAdminServer_dataElementCpuLoad`: CPU load, type: float.
	* `c_HostAdminServer_dataElementMemUsage`: memory usage in kilobytes, type: integer.
	* `c_HostAdminServer_dataElementMemUsageHRF`: memory usage in human readable format, type: charstring.

	For example, the Variable name for the CPU usage statistics of EPTF component with `selfName` "SIPLGen2" can be get with the following:

	`f_EPTF_HostAdminServer_getProcessVarNamePrefix("IPLGen2") & c_HostAdminServer_dataElementCpuLoad`

	== Summary Table of All Public Functions for EPTF Host Admin

	See Summary of Host Admin functions below:

	[width="100%",cols="50%,50%",options="header",]
	\|==========================================================================================================
	\|Function name \|Description
	\|`f_EPTF_HostAdmin_Base_InitMeasInterface` \|Initializes the Host Admin Base Component
	\|`f_EPTF_HostAdmin_Base_CleanupMeasInterface` \|Should be called before stopping the Host Admin Base component
	\|`f_EPTF_HostAdmin_Base_update` \|Updates measurement data
	\|`f_EPTF_HostAdmin_Base_getProcessName` \|Get the name of a process by PID
	\|`f_EPTF_HostAdmin_Base_addProcessStat` \|Add process statistics by PID
	\|`f_EPTF_HostAdmin_Base_removeProcessStat` \|Remove process statistics by PID
	\|`f_EPTF_HostAdmin_Base_removeProcessStatByIdx` \|Remove process statistics by index
	\|`f_EPTF_HostAdmin_Base_getProcessCpuLoad` \|Get CPU load of process by PID
	\|`f_EPTF_HostAdmin_Base_getProcessCpuLoadByIdx` \|Get CPU load of process by index
	\|`f_EPTF_HostAdmin_Base_getProcessMemUsage` \|Get memory usage of process by PID
	\|`f_EPTF_HostAdmin_Base_getProcessMemUsageByIdx` \|Get memory usage of process by index
	\|`f_EPTF_HostAdmin_behavior` \|Behavior function that should be started on Host Admin component
	\|`f_EPTF_HostAdminServer_init_CT` \|Initilize Host Admin Server
	\|`f_EPTF_HostAdminServer_setSortBy` \|Set the sort order for pre host process statistics
	\|`f_EPTF_HostAdminServer_getProcessVarNamePrefix` \|Get Variable name prefix for process stats by `selfName`
	\|==========================================================================================================

	== `DataSource` Client Functionality

	The Host Admin feature provides `DataSourceClient` functionality. This means that a `HostAdmin` component has several Variables, that are available to use with the help of a `DataSource` server, for example the `UIHandler`. With the call of the function `f_EPTF_UIHandler_createGUI()`, a custom GUI is built, and the data of the features are freely to use. For more info about the `DataSource` feature, see the `UIHandler` Function Description <<_6, [7]>>. For the list of the existing iterators and external data elements, see the natural documentation.

	= Terminology

	TitanSim Core (Load) Library(CLL): +
	It is that part of the TitanSim software that is totally project independent. (I.e., which is not protocol-, or application-dependent). The TitanSim CLL is to be supplied and supported by the TCC organization. Any TitanSim CLL development is to be funded centrally by Ericsson.

	EPTF Variable: +
	An enhanced component variable that makes it possible to access the values of other Variables in remote components.

	= Abbreviations

	CLL:: Core Load Library

	EPTF:: Ericsson Load Test Framework, formerly TITAN Load Test Framework

	MTC:: Main Test Component

	TitanSim:: Ericsson Load Test Framework, formerly TITAN Load Test Framework

	TTCN-3:: Testing and Test Control Notation version 3 <<_1, [1]>>

	= References

	[[_1]]
	[1] ETSI ES 201 873-1 v3.2.1 (2007-02) +
	The Testing and Test Control Notation version 3. Part 1: Core Language

	[[_2]]
	[2] User Guide for the TITAN TTCN-3 Test Executor

	[[_3]]
	[3] TitanSim CLL for TTCN-3 toolset with TITAN, Function Specification

	[[_4]]
	[4] TitanSim CLL for TTCN-3 toolset with TITAN +
	http://ttcn.ericsson.se/products/libraries.shtml[Reference Guide]

	[[_5]]
	[5] EPTF CLL Variable, Function Description

	[[_6]]
	[6] EPTF CLL UIHandler, Function Description