blob: 4c0e9a03665fa01e50dded597f94573b760ee5d1 [file] [log] [blame]
---
Author: László Skumát
Version: 21/198 17-CNL 113 512, Rev. C
Date: 2011-09-06
---
= EPTF CLL Load Regulator, User Guide
:author: László Skumát
:revnumber: 21/198 17-CNL 113 512, Rev. C
:revdate: 2011-09-06
:toc:
== About This Document
=== How to Read This Document
This is the User Guide for the Load Regulator 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 Load Regulator feature <<_5, [5]>>. For more information on the TitanSim, consult the User's Guide <<_4, [4]>> and the Function Specification <<_3, [3]>> of the TitanSim.
== System Requirements
In order to use the Load Regulator feature, the system requirements listed in TitanSim CLL User Guide <<_4, [4]>> should be fulfilled.
= Load Regulator
== Overview
The EPTF CLL Load Regulator component is a fundamental component providing an implementation for load regulation based on the SUT load in a load test environment. It can also regulate load for a target network bandwidth usage.
The function used to measure the SUT load or the bandwidth must be provided by the user, passing its function reference to the initialization function. The load regulation is implemented by calculating the next CPS from the previous CPS and the last two loads, according to the specified load to reach.
[[desc_files_this_feat]]
== Description of Files in This Feature
The EPTF CLL Load Regulator API includes the following files:
* Load Regulator
** __EPTF_CLL_LoadRegulator_Definitions.ttcn__ - This TTCN-3 module contains type definitions that should be used in all Load Regulator Components.
** __EPTF_CLL_LoadRegulator_Functions.ttcn__ - This TTCN-3 module contains the implementation of Load Regulator functions.
[[desc_req_files_other_feat]]
== Description of Required Files From Other Features
The Load Regulator feature is part of the TitanSim EPTF Core Load Library (CLL). It relies on several features of the CLL. To use the Load Regulator, the user has to obtain the respective files from the following features:
* `Base`
* `Common`
* `DataSource`
* `Logging`
* `Variable`
== Installation
Since `EPTF_CLL_LoadRegulator` 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_LoadRegulator`:
* Copy the files listed in section <<desc_files_this_feat, Description of Files in This Feature>> and <<desc_req_files_other_feat, Description of Required Files From Other Features>> to the directory of the test suite or create symbolic links to them.
* Import the Load Regulator demo or write your own application using Load Regulator.
* 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 <<config, Configuration>>.
[[config]]
== 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]>>.
The Load Regulator feature 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.
The Load Regulator feature defines the following module parameters (all defined in module `EPTF_CLL_LoadRegulator_Functions`):
* `tsp_debug_EPTF_CLL_LoadRegulator_Functions`
+
This boolean type module parameter can be used to enable debug logging of the Load Regulator.
+
Its default value is `_false_`.
* `tsp_debug_EPTF_CLL_LoadRegulator_Functions_smooting`
+
This boolean type module parameter can be used to enable debug logging of the load smoothing implemented in the Load Regulator.
+
Its default value is `_false_`.
* `tsp_EPTF_loadRegulator_measWinSize`
+
This integer module parameter defines the load measurement window size.
+
Its default value is `_"3"_`, which should not be modified if the default CPS calculation function is used.
* `tsp_EPTF_loadRegulator_updateTimeout`
+
This float type module parameter defines the interval of the load regulation update period in seconds.
+
Its default value is `_2.0_`.
* `tsp_EPTF_loadRegulator_LoadVarianceThreshold`
+
This float type module parameter defines the minimum load variance that should result in regulation of the load, in percentage.
+
Its default value is `_5.0_` for 5%.
* `tsp_EPTF_loadRegulator_cpsDelta`
+
This float type module parameter defines the maximum CPS increase/decrease per regulation cycle.
+
* `tsp_EPTF_loadRegulator_errorTolerance`
+
This float type module parameter defines the load delta tolerance in percents.
+
Its default value is `_5.0_`.
* `tsp_EPTF_loadRegulator_smoothingFactor`
+
This float type module parameter defines the smoothing factor for exponential load measurement smoothing.
+
Its default value is `_0.5_`.
= Examples
The "demo" directory of the deliverable contains the following examples:
* __EPTF_LoadRegulator_demo.cfg__
* __EPTF_LoadRegulator_demo.prj__
* __EPTF_LoadRegulator_demo.ttcn__
== Configuration File
The used configuration file (_EPTF_LoadRegulator_demo.cfg_) for the Load Regulator example is placed in the demo directory.
Module parameters of the demo (additional to the ones described in <<config, Configuration>>):
* `tsp_demoInterval`: interval of testing. Type: float, default: `_300.0_`.
* `tsp_demoLoadGenerationPeriod`: load generation period, defined the time interval with which the load is generated as bursts. Type: float, default: `_0.1_`.
* `tsp_demoLoadToReach`: processor load to reach in percents. Type: float, default: `_25.0_`.
* `tsp_demoCpsToReach`: initial CPS value. Type: float, default: `_10.0_`
* `tsp_NetInterfaceName`: network interface name. Type: charstring, default: `_"eth0"_`.
* `tsp_bandwidthToReach`: bandwidth to reach in kB/s. Type: float, default: `_150.0_`.
== Demo Module
The demo module (__EPTF_LoadRegulator_demo.ttcn__) illustrates a typical usage of the Load Regulator feature.
The testcase `tc_LoadRegulator_demo` demo implements a simple (and not accurate) load generator and a repeater component. The Load Regulator feature is used in the simple load generator to regulate the number of messages that is to be sent per seconds to the repeater component, based on the average processor load measurement taken by the Host Admin Base feature <<_7, [7]>>.
The testcase `tc_LoadRegulator_weightedCPC_demo` uses a post-CPS-calculation function for distributing the calculated CPS to a weighted CPS list.
The testcase `tc_BandwidthLimitedTrafficControl_demo` regulates the load based on the measured network bandwidth according to the module parameter `tsp_bandwidthToReach`.
= 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.
= Abbreviations
CLL:: Core Load Library
EPTF:: Ericsson Load Test Framework, formerly TITAN Load Test Framework
TitanSim:: Ericsson Load Test Framework, formerly TITAN Load Test Framework
TTCN-3:: Testing and Test Control Notation version 3 <<_1, [1]>>.
SUT:: System Under Test
CPS:: Calls Per Second
= 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 Load Regulator, 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 Host Admin, User Guide