---
Author: Balázs Lugossy
Version: 20/198 17-CNL 113 512, Rev. E
Date: 2012-03-26

---
= EPTF CLL Host Admin, User Guide
:author: Balázs Lugossy
:revnumber: 20/198 17-CNL 113 512, Rev. E
:revdate: 2012-03-26
:toc:

== About This Document

=== How to Read This Document

This is the User Guide 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]>>. This document should be read together with the Function Description of the Host Admin feature <<_5, [5]>>. For more information on the TitanSim CLL, consult the Users Guide <<_4, [4]>> and the Function Specification <<_3, [3]>> of the TitanSim.

== System Requirements

In order to use the Host Admin feature the system requirements listed in TitanSim CLL User Guide [5] should be fulfilled.

The Host Admin feature supports the following operating systems:

* Solaris 5.6
* Solaris 5.8
* Linux
* Win32 / Cygwin

= Host Admin

== Overview

The EPTF CLL Host Admin component is a fundamental component providing an implementation for host processor load and memory usage measurement in a load test environment.

The Host Admin 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 via EPTF Variables (or a local measurement interface running in a separate component).

There is an additional component type called Host Admin Server that, if initialized on a component (preferably the MTC), can automatically start Host Admin servers on hosts that take part in running TitanSim and collect all host and EPTF process statistics from these Host Admins. The statistics are available through Data Sources.

[[description_of_files_in_this_feature]]
== Description of Files in This Feature

The EPTF CLL Host Admin API includes the following files:

* Host Admin Base
** __EPTF_CLL_HostAdmin_Base_Definitions.ttcn__: This TTCN-3 module contains common type definitions that should be used in all Host Admin Base Components.
** __EPTF_CLL_HostAdmin_Base_Functions.ttcn__: This TTCN-3 module contains the implementation of Host Admin Base.
* Host Admin
** __EPTF_CLL_HostAdmin_Definitions.ttcn__: This TTCN-3 module contains common type definitions that should be used in all Host Admin Components.
** __EPTF_CLL_HostAdmin_Functions.ttcn__: This TTCN-3 module contains the implementation of Host Admin.
** __EPTF_CLL_HostAdmin_DSFunctions.ttcn__: This TTCN-3 module contains the implementation of Host Admin `DataSource` functionality.
* Host Admin Server
** __EPTF_CLL_HostAdminServer_Definitions.ttcn__: contains type definitions used by the Host Admin Server
** __EPTF_CLL_HostAdminServer_Functions.ttcn__: contains the implementation of the Host Admin Server

[[description_of_required_files_from_other_features]]
== Description of Required Files From Other Features

The Host Admin feature is part of the TitanSim EPTF Core Load Library (CLL). It relies on several features of the CLL. To use the Host Admin, the user has to obtain the respective files from the following features:

* `Base`
* `Variable`
* `Common`
* `HashMap`
* `Free Busy Queue`
* `LOADMEASasp_PT testport`
* `DataSource`
* `Red Black Tree`

== Installation

Since `EPTF_CLL_HostAdmin` is used as a part of the TTCN-3 test environment this requires TTCN-3 Test Executor to be installed before any operation of these functions. For more details on the installation of TTCN-3 Test Executor see the relevant section of <<_2, [2]>>.

If not otherwise noted in the respective sections, the following are needed to use `EPTF_CLL_HostAdmin`:

* Copy the files listed in section <<description_of_files_in_this_feature, Description of Files in This Feature>> and <<description_of_required_files_from_other_features, Description of Required Files From Other Features>> to the directory of the test suite or create symbolic links to them.
* Import the Host Admin demo or write your own application using Host Admin.
* Create _Makefile_ or modify the existing one. For more details see the relevant section of <<_2, [2]>>.
* Edit the config file according to your needs, see following section <<configuration, Configuration>>.

[[configuration]]
== Configuration

The executable test program behavior is determined via the run-time configuration file. This is a simple text file, which contains various sections. The usual suffix of configuration files is _.cfg_. For further information on the configuration file see <<_2, [2]>>.

This set of protocol modules defines TTCN-3 module parameters as defined in <<_2, [2]>>, clause 4. Actual values of these parameters – when no default value or a different from the default actual value wished to be used – shall be given in the `[MODULE_PARAMETERS]` section of the configuration file.

This protocol module defines the following module parameters:

* `tsp_debug_EPTF_HostAdmin_Base_Functions`
+
This boolean type module parameter is defined in module `EPTF_CLL_HostAdmin_Base_Functions`. It can be used to enable debug logging of the Host Admin Base feature.
+
Default value: `_false_`.

* `tsp_debug_EPTF_HostAdmin_Base_Functions_smoothing`
+
This boolean type module parameter is defined in module `EPTF_CLL_HostAdmin_Base_Functions`. It can be used to enable debug logging of the smoothing parameters.
+
Default value: `_false_`.

* `tsp_EPTF_HostAdmin_loadMeasurementExponentialSmoothingFactor`
+
This float type module parameter is defined in module `EPTF_CLL_HostAdmin_Base_Functions`. It is used to define the level of CPU measurement smoothing.
+
Default value is `_0.5_`. It should be between `_0.0_` and `_1.0_`.

* `tsp_EPTF_HostAdmin_loadMeasurementRefreshTime`
+
This float type module parameter is defined in module `EPTF_CLL_HostAdmin_Base_Functions`. It is used to define the periodical update time with which the `LOADMEASasp` testport and Host Admin should update t+he measurement variables.

* `tsp_debug_EPTF_HostAdmin_Functions`
+
This boolean type module parameter is defined in module `EPTF_CLL_HostAdmin_Functions`. It can be used to enable debug logging of the Host Admin feature.
+
Default value: `_false_`.

* `tsp_EPTF_HostAdmin_pidList`
+
This parameter is defined in module `EPTF_CLL_HostAdmin_Definitions`. It can be used to specify a list of process PIDs for each host. The `HostAdmin` will create EPTF variables for PID, name, CPU and memory usage for each of these processes and update these with the measured values.

* `tsp_EPTF_HostAdmin_getProcessPidListCmds`
+
This parameter is deprecated – not used. Since process ids are retrieved via `EPTF_Base` feature, PIPE TP dependency is eliminated and so no use of this module parameter anymore.

* `tsp_EPTF_HostAdmin_sortBy`
+
This parameter decides how to sort the process list sent from the Host Admin to the Host Admin Server. The possible values are: `_SelfName_`, `_CpuLoad_`, `_MemUsage_`, `_DontSort_`.
+
The default value is `_CpuLoad_`.

* `tsp_debug_EPTF_HostAdminServer_Functions`
+
This boolean type module parameter is defined in module `EPTF_CLL_HostAdminServer_Functions`. It can be used to enable debug logging of the Host Admin Server feature.
+
Default value: `_false_`.

* `tsp_EPTF_HostAdminServer_processListRefreshInterval`
+
This float type module parameter is defined in module `EPTF_CLL_HostAdmin_Definitions`. It defines the interval used to refresh the list of EPTF processes from the Base feature.
+
Default value: `_1.0_`.

=== EPTF Variables Defined by Host Admin

The Host Admin defines the following EPTF Variables <<_7, [7]>>:

[width="100%",cols="34%,33%,33%",options="header",]
|================================================================================================
|*Name* |*Type* |*Description*
|`testerHostLoad` |float |Average CPU load
|`numCPUs` |integer |number of processors
|`CPULoads.X` |float |processor load for CPU X, where X is an integer ranging from 0 to (numCPUs-1)
|`physicalMemory` |integer |physical memory in kilobytes
|`freeMemory` |integer |free/available memory in kilobytes
|`nofProcessStats` |integer |number of process statistics
|`process.Y.PID` |integer |PID of the process
|`process.Y.Name` |charstring |name of the process
|`process.Y.CPU` |float |CPU load of the process in percents
|`process.Y.MEM` |integer |memory usage of the process in kB
|================================================================================================

The name of these variables is prefixed with the EPTF name of the Host Admin component, which was passed to the behaviour function, followed by a dot ("."). The X after "CPULoads." specifies the index of the processor, ranging from `_0_` to `_(numCPUs-1)_`. For example, the load of the second processor on a Host Admin with name `_"MyHostAdmin"_` would have the following variable name: ``MyHostAdmin.CPULoads.1''. The Y is the index of the process statistics, e.g. `"MyHostAdmin.process.0.PID"`, ranging from `_0_` to `(nofProcessStats-1)`.

=== `DataSource` Elements Defined by Host Admin

See in the natural documentation of the Host Admin feature.

= Error messages

Please note, that besides the below described error messages, error messages shown in <<_2, [2]>> or those of other used features or product may also appear.

There are no error messages defined in HostAdmin feature.

= Warning Messages

NOTE: Besides the below described warning messages, warning messages shown in <<_2, [2]>> or those of other used features or product may also appear.

`*f_EPTF_HostAdmin_DSProcessData: Invalid processID on this Host*`

This warning message is reported when the `DataSource` functionality is used and the current data element needs a process ID as a parameter and it is wrong.

`*f_EPTF_HostAdmin_DSProcessData: Unhandled element:*`

This warning message is reported when the `DataSource` functionality is used and the current data element is unknown for the feature.

`*f_EPTF_HostAdmin_DSProcessData: Invalid iterator or externalData or parameter:*`

This warning message is reported when the `DataSource` functionality is used and the something with the request was wrong.

`*f_EPTF_HostAdmin_getParams: Parameters are not correct:*`

This warning message is reported when the `DataSource` functionality is used and the parameters of the current data element are not correct.

`*f_EPTF_HostAdmin_getParams: Too few parameter is given:*`

This warning message is reported when the `DataSource` functionality is used and the parameters of the current data element are less than required.

`*f_EPTF_HostAdmin_getParams: Too many parameters are given:*`

This warning message is reported when the `DataSource` functionality is used and the parameters of the current data element are more than required.

= Examples

The "demo" directory of the deliverable contains the following examples:

* __EPTF_HostAdmin_demo.cfg__
* __EPTF_HostAdmin_demo.prj__
* __EPTF_HostAdmin_demo.ttcn__
* __makefile_patch.sh__

== _Makefile_

The _Makefile_ for projects using the Host Admin or Host Admin Base has to be modified from the _Makefile_ generated by TITAN.

The following modifications are needed in the _Makefile_ to be able to build the executable:

* Add `-lkstat –lpthread` to `SOLARIS_LIBS` and `SOLARIS8_LIBS`
* Add `-lpthread` to `LINUX_LIBS` and `WIN32_LIBS`

The example script __makefile_patch.sh__ in the demo directory can do this automatically.

== Configuration File

The used configuration file (__EPTF_HostAdmin_demo.cfg__) for the Host Admin example is placed in the demo directory.

Module parameters of the demo (additional to the ones described in <<2.5):

* `tsp_demoInterval`: interval of testing. Type: float, default: `_30.0_`.
* `tsp_demoRefreshPeriod`: refresh period for the local measurement test case in seconds. Type: float, default: 2.0.
* `tsp_demoHost`: host name or IP address for the remote measurement test case. Type: charstring, default: ``127.0.0.1''.
* `tsp_uiDemoHostList`: list of hosts for the `HostAdminUI` demo. If it is empty, `tsp_demoHost` is used instead.

== Demo Module

The demo module (__EPTF_HostAdmin_demo.ttcn__) illustrates a typical usage of the Host Admin feature.

There are three testcases in the demo:

* `tc_HostAdmin_RemoteMeasure`: example usage of the standalone Host Admin component.
* `tc_HostAdmin_LocalMeasure`: example usage of the Host Admin Base component.
* `tc_HostAdmin_GUI`: example usage of the `HostAdminUI`.
* `tc_HostAdminServer`: example usage of the Host Admin Server.

= 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

PID:: Process Identifier

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, User Guide

[[_5]]
[5] EPTF CLL Host Admin, Function Description

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

[[_7]]
[7] EPTF CLL Variable, User Guide