---
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