Rational Performance Tester Load Generation Agent

Architecture and Support

RPT Version 8.3.0

Kevin Mooney (kmooney@us.ibm.com) Richard Ptasnik (ptasnik@us.ibm.com)

Table of ontents
1. Load Generation Agent Introduction 2. Agent Controller 3. Architecture 4. Installation 4.1 Workbench Local Execution 4.2 Installation eatures 4.3 Load Generation Agent Con!iguration 5. Workbench Con!iguration 5.1 #er$er %ort 5.2 #ecure Co&&unication using 'L#(##L 5.3 *elete *e+lo,&ent *irector, ". Con!iguration -odi!ication ".1 Add #u++ort !or Another Workstation to an Agent ".2 Load Generation Agent Con!iguration ile ). Agent #tatus ).1 #hare Agent 0ith 1e0 Workbench ).2 *isconnect Agent !ro& this Workbench .. 'roubleshooting ..1 %ort In 2se ..2 Check Agents ailed ..3 %rocess on dri$er ter&inated /. 'i+s4 'ricks and -iscellaneous /.1 %ri$ileges /.2 -ulti+le Engines 5n 5ne Agent -achine /.3 Locations /.4 %orts 0ith &ulti+le 0orkbenches /.5 -ax hea+ /." -a6ordo&o /.) -a6ordo&o debug !lag 3 4 4 5 5 5 " " " ) ) ) ) . / / / / / 13 11 13 13 13 13 13 13 14 14

!.

Load Generation Agent "ntroduction

A ne0 Load Generation Agent is a $ital +art o! 7ational %er!or&ance 'ester 87%'9 :ersion ..3.3. As a re+lace&ent !or the Agent Controller the Load Generation Agent o!!ers the !ollo0ing !eatures; :er, strong execution +rocess launch reliabilit, !or agents. 'he Load Generation Agent is designed s+eci!icall, to 0ork 0ith the 7ational %er!or&ance 'ester 0orkbench in the launch and control o! load tests. Agents +oll su++orted 0orkbenches looking !or schedule execution 0ork instead o! the 0orkbench ha$ing to establish connections 0ith agents. 'his sche&e +ro$ides instant assess&ent o! agent readiness and ra+id deli$er, o! launch co&&ands. With the Load Generation Agent the 0orkbench is ca+able o! launching agents in +arallel thus greatl, reducing o$erall launch ti&e !or large load testing o+erations in$ol$ing &an, agents. 'he Load Generation Agent su++orts intelligent test asset de+lo,&ent onl, +ulling assets !ro& the 0orkbench that it does not ha$e or that ha$e changed. 'his !eature results in !aster launch ti&es !or subse<uent executions. 'he Load Generation Agent uses an =''% ser$er and the =''% +rotocol bet0een the 0orkbench and agents. Loss o! a connection si&+l, &eans another is established 0ith no har& to the o$erall execution +ro$iding robustness during &ulti>da, executions. 'he Load Generation Agent is &ore !ire0all !riendl,4 re$ersing the contact initiation such that agents connect to the 0orkbench instead o! $ice $ersa. 'he use o! an =''% ser$er 0ithin the 0orkbench &eans the custo&er has onl, one +ort to con!igure 0ith the !ire0all instead o! the &an, +orts on both ends that the Agent Controller re<uired. #ecure co&&unications are &uch easier 0ith the Load Generation Agent. 'he +re!erence to secure co&&unication bet0een 0orkbench and all agents can be done !ro& the 0orkbench instead o! ha$ing to con!igure each indi$idual agent.

#.

Agent

ontroller

'he Agent Controller is still +ro$ided 0ith $ersion ..3.3. As an o+tional +art o! the installation the Agent Controller can be installed in order to su++ort these !eatures; 7es+onse 'i&e ?reakdo0n 87'?9 #er$ice>oriented Architecture 8#5A9 #tubs

While not a t,+ical custo&er con!iguration installing both the Load Generation Agent and the Agent Controller is a su++orted con!iguration. The Agent Controller cannot be used for load generation with the RPT 8.3.0 workbench.

3.

Architecture

'his section describes the architecture o! the Load Generation Agent. 2nlike the Agent Controller architecture the 0orkbench does not &ake connections to the agents 0hen a schedule is to be executed. 'he +orts that had to be o+ened b, !ire0alls !or those connections and the connections the agents &ade back to the 0orkbench on e+he&eral +orts are no longer necessar,. With the Load Generation Agent the agent &achines +oll !or 0ork sending =''% re<uests to the 7ational %er!or&ance 'ester #er$er running 0ith the 0orkbench. When a custo&er +resses the 7un button to start schedule execution the next ti&e a +artici+ating agent contacts the 0orkbench it res+onds to the agent indicating its +artici+ation is needed. 'he agent then launches the execution engine as the Agent Controller 0ould ha$e. 'he execution engine then contacts the 7%' #er$er and the usual exchange o! co&&ands to begin schedule execution co&&ences.

Workbench

ScheduleExecutor

LoadTestExecutor LoadTestExecutor

RPT Server

HTTP

HTTP

HTTP

Agent Majordomo Domo

Runner/Eng ne

Domo
Runner/Eng ne

In the !igure abo$e the Workbench box re+resents the Ecli+se user inter!ace o! 7ational %er!or&ance 'ester 0hich is a single +rocess and one @a$a :irtual -achine 8@:-9. 7ational %er!or&ance 'ester ..3.3 also includes the 6ett, 0eb ser$er to su++ort co&&unication bet0een the 0orkbench and agents. Within the 0orkbench each agent has a Load'estExecutor !or co&&and4 control and state &anage&ent o! each agent.

5n a single agent there exists the -a6ordo&o ser$ice 0hich is one @a$a :irtual -achine that +olls su++orted 0orkbenches !or schedule execution 0ork. Each *o&o box in the !igure is a single @a$a :irtual -achine and includes the execution engine. ',+icall, there 0ill be onl, one @a$a +rocess running on the agent during schedule execution. 'hat single @a$a +rocess is the *o&o(Engine +rocess. 'he !igure abo$e sho0s that it is +ossible !or one agent &achine to su++ort &ulti+le execution engines. Custo&ers that ha$e a +o0er!ul "4>bit agent 0ith a lot o! &e&or, &a, !ind it o$erall &ore e!!icient to run 0ith &ulti+le engine +rocesses o! &odest hea+ siAe than one single +rocess 0ith enor&ous hea+ siAe due to garbage collection considerations. 'he Load Generation Agent is designed to be si&+le and co&+act. 'he *o&o co&+onent do0nloads !ro& the 0orkbench the assets needed !or schedule execution4 including the execution engine. 5n subse<uent executions *o&o onl, do0nloads assets that ha$e changed since the +re$ious execution.

$.

"nstallation

'he installation o! the Load Generation Agent is si&ilar to the installation o! the Agent Controller. In !act4 both !eatures are a$ailable 0hen ,ou install the 7ational %er!or&ance 'ester Agent +roduct !or $ersion ..3.3. $.! %or&bench Local '(ecution While installing the 7ational %er!or&ance 'ester Agent +roduct 0ith the 0orkbench +roduct is a su++orted con!iguration it is not re<uired. As 0ith +re$ious releases it is +ossible to execute schedules locall, on the sa&e &achine that the 0orkbench is running on 0ithout ha$ing to install the 7ational %er!or&ance 'ester Agent +roduct. 'he 0orkbench 0ill auto&aticall, s+a0n an instantiation o! the Load Generation Agent to su++ort local execution during the li!e o! the execution o! the schedule. $.# "nstallation )eatures

?, de!ault a 7ational %er!or&ance 'ester Agent installation 0ill install the Load Generation Agent and not install the Agent Controller.

$.3 Load Generation Agent onfiguration 'he Load Generation Agent has t0o con!iguration +ara&eters that need to be entered during installation.

Workbench hostna&e. Enter one and onl, one hostna&e that this agent 0ill +oll !or 0ork. Workbench +ort. Enter the +ort nu&ber su++orted b, the 0orkbench. 'he de!ault +ort nu&ber is )3.3.

*.

%or&bench

onfiguration

'he Load Generation Agent has se$eral o+tions that can be con!igured !ro& the 0orkbench. 'hese o+tions do not re<uire changes on the agent. Con!igure Load Generation Agent o+tions $ia Windo0 B %re!erences B 'est B #er$er.

*.! Ser+er Port #elect the unsecure and secure +orts the ser$er 0ill use !or co&&unication 0ith agents. ?, de!ault co&&unication is unsecure and so the unsecure +ort is the onl, one that &a, need to be changed. 'he +ort does not ha$e to be changed unless it is alread, in use b, another +roduct running on the 0orkbench. I! ,ou change the 0orkbench +ort the agent con!iguration &ust also be changed to use the sa&e +ort. 'he secure +ort is onl, used 0hen running 0ith the o+tion to encr,+t &essages bet0een the 0orkbench an agent. 'he con!iguration o! the secure +ort nu&ber is onl, done on the 0orkbench. 'here is no con!iguration change re<uired on the agent related to the secure +ort.

*.# Secure ommunication using TLS,SSL Check Workbench and agent communication is encry ted using T!"#""! to ha$e all &essages and execution data exchanged bet0een the 0orkbench and agents encr,+ted. All schedules executed !ro& this 0orkbench 0ill use ##L. 'he 0orkbench 0ill tell the agent 0hat +ort to use !or secure co&&unication $ia the unsecure +ort +rior to starting schedule execution. *.3 -elete -eplo.ment -irector. Check $elete de loyment directory on the agent after e%ecution to ha$e the contents o! the de+lo,&ent director, re&o$ed !ro& the agent a!ter schedule execution co&+letes. 'he de+lo,&ent director, contains all the test assets the agent re<uires in order to +artici+ate in schedule execution. #electing this o+tion de!eats the cached test assets launch ti&e i&+ro$e&ent !eature &aking subse<uent schedule launch ti&es no shorter than the !irst schedule launch. 'he !eature 0ould be o! interest to custo&ers concerned about disk s+ace accu&ulating on the agent !ro& &an, di!!erent schedule executions.

/.

onfiguration 0odification

5nce a 0orkbench and &an, agents are installed it &a, beco&e necessar, to &ake con!iguration changes. 'his section describes ho0 to &odi!, an agent con!iguration a!ter installation. /.! Add Support for Another %or&station to an Agent I! ,ou recall !ro& the Installation section it 0as onl, +ossible to s+eci!, the hostna&e o! one agent 0hen con!iguring the Load Generation Agent. #o 0hat ha++ens i! ,ou add another 0orkstation to the lab and 0ant an agent to su++ort itC 'he reco&&ended a++roach is to use the Agent #tatus button on an alread, su++orted 0orkbench to add the ne0 0orkbench to the agentDs con!iguration.

When ,ou +ress the Agent #tatus button a 0indo0 a++ears sho0ing the status o! agents in contact 0ith this 0orkbench. 'o ha$e an agent su++ort another 0orkbench in the lab check the box beside the agent and +ress the button labeled "hare Agent with &ew Workbench.

Eou 0ill then be +ro&+ted to enter the hostna&e and +ort nu&ber !or the 0orkbench to add to the agentFs con!iguration. A!ter +ressing the 5G button the re<uest to add the ne0 0orkbench 0ill be deli$ered to the agent. Within a short ti&e the agent should begin +olling the ne0 0orkbench !or schedule execution 0ork. /.# Load Generation Agent onfiguration )ile A!ter installation o! the 7ational %er!or&ance 'ester Agent 0ith the Load Generation Agent !eature there 0ill be an agent con!iguration !ile stored on the agent. ?, editing4 co+,ing or re+lacing the con!iguration !ile ,ou can do the !ollo0ing; Change the hostna&e o! a 0orkbench the agent +olls !or 0ork Change the +ort the agent 0ill use 0hen contacting the 0orkbench Add one or &ore additional 0orkbenches !or the agent to su++ort 7e+lace the entire con!iguration en &asse b, co+,ing o$er the existing con!iguration !ile %ush a ne0 con!iguration out to &an, agents using re&ote co+, co&&ands

'he Load Generation Agent 0ill re!resh its con!iguration based on the contents o! the !ile in about ten seconds a!ter the change is &ade. 'here is no need to sto+ and restart the agent ser$ice. 'he contents o! the con!iguration !ile are H-L and the !or&at is intuiti$e. ?elo0 is an exa&+le con!iguration !ile !or an agent that is su++orting t0o 0orkbenches.

<MajordomoConfig xmlns="http://www.example.org/MajordomoConfiguration"> <debug>false</debug> <workben hes> <host!ame>deepglue.rtp.raleigh.ibm. om</host!ame> <port>"#$#</port> </workben hes> <workben hes> <host!ame>athena.rtp.raleigh.ibm. om</host!ame> <port>"#$#</port> </workben hes> </MajordomoConfig>

'he Load Generation Agent con!iguration !ile is stored t,+icall, in one o! these locations; C;I%rogra& ilesII?-I#*%I-a6ordo&oI&a6ordo&o.con!ig 8Windo0s "4>bit9 C;I%rogra& iles 8x."9II?-I#*%I-a6ordo&oI&a6ordo&o.con!ig 8Windo0s 32>bit9 ($ar(o+t(I?-(#*%(-a6ordo&o(&a6ordo&o.con!ig 82nix9

1.

Agent Status

As &entioned abo$e4 the 0orkbench contains an Agent #tatus button. When selected it is +ossible to see 0hat agents are +olling the 0orkbench !or 0ork and i! the, are read, to +artici+ate in schedule execution.

'he states an agent &a, dis+la, are; 7ead,. 'he agent is read, to execute a schedule. ?us,. 'he agent is read, to execute a schedule. 'he agent is currentl, executing a schedule. It is +ossible !or an agent to be executing &ore than one schedule at a ti&e. Lost Contact. 'he agent is no longer +olling this 0orkbench.

1.! Share Agent 2ith 3e2 %or&bench I! ,ou select one or &ore agents and +ress "hare Agent with &ew Workbench ,ou can s+eci!, the hostna&e and +ort o! a ne0 0orkbench that ,ou 0ant the agent to +oll !or 0ork in addition to the this 0orkbench. 1.# -isconnect Agent from this %or&bench I! ,ou select one or &ore agents and +ress $isconnect Agent from this Workbench the hostna&e !or this 0orkbench 0ill be re&o$ed !ro& the agentsD con!iguration !iles and the, 0ill no longer +oll this 0orkbench !or 0ork.

8.

Troubleshooting

'his section describes so&e co&&on +roble& scenarios and +ro$ides suggestions !or !inding a solution. 8.! Port "n 4se "ym tom When ,ou tr, to run a schedule the !ollo0ing error &essage dialog a++ears;

'eaning #o&e +roduct running on the 0orkbench is alread, using +ort )3.34 the de!ault unsecure +ort 7%' uses !or co&&unication 0ith agents. "olution () 2sing Windo0 B %re!erences B 'est B #er$er choose a di!!erent +ort such as )3.1. All agentDs con!iguration !iles &ust also s+eci!, +ort )3.1. 'here is no need to restart the 0orkbench !or this change to take e!!ect. "olution (* It is +ossible the +roduct using +ort )3.3 is no longer needed on this &achine. I! so4 sto+ or uninstall the +roduct using +ort )3.3. 8.# hec& Agents )ailed "ym tom When ,ou tr, to run a schedule the !ollo0ing error &essage dialog a++ears;

'eaning 5ne or &ore o! the agents listed to +artici+ate in executing this schedule are not in acti$e contact 0ith this 0orkbench. 'he Agent #tatus button can be used to $ie0 agent status +rior to schedule execution to deter&ine the likelihood o! encountering the Check Agents ailed &essage. "olution () 'he 7%' Agent is not installed. 5n an agent ,ou can use the I?- Installation -anager :ie0 Installed %ackages !eature to ensure that the 7ational %er!or&ance 'ester Agent is installed. "olution (* 'he Load Generation Agent is installed but the agent ser$ice4 -a6ordo&o4 is not running. Windows Look !or the -a6ordo&o#er$ice +rocess. I! not running; cd +Program ,iles#"$P#-.'#'a/ordomo0 &1A"tart Look !or the -a6ordo&o +rocess. I! not running; cd #o t#-.'#"$P#'a/ordomo .#'$"tart.sh

Unix

Enter the co&&ands abo$e using co&&and +ro&+t or a shell. #ubstitute a++ro+riate +aths based on installation. 2se 'ask -anager 8Windo0s9 or the +s co&&and 82nix9 to $eri!, the agent is running. Look !or -a6ordo&o on 2nix s,ste&s. 5n Windo0s s,ste&s look !or -a6ordo&o#er$ice.exe. "olution (3 -a6ordo&o is running on the agent but it is not +olling the 0orkbench !or 0ork. :eri!, that the agent can *1# resol$e the hostna&e as s+eci!ied in the con!iguration !ile. 2se the ing co&&and s+eci!,ing the 0orkbench hostna&e exactl, as entered in the &a6ordo&o.con!ig !ile. I! the +ing co&&and !ails using the hostna&e but ,ou can success!ull, +ing the 0orkbench using its I% address a 0orkaround could be to s+eci!, the 0orkbench I%

address in &a6ordo&o.con!ig instead o! the host na&e. "olution (2 I! -a6ordo&o is running and the 0orkbench can be +inged !ro& the agent then $eri!, there is not a !ire0all blocking access. ro& a co&&and +ro&+t or shell enter the !ollo0ing; telnet W3R4.5&C6763"T7&A'5 8080 ',+e a !e0 characters and +ress Enter. Eou should see the !ollo0ing;

I! unable to connect or ,ou do not recei$e a res+onse like the one abo$e +erha+s tr, te&+oraril, disabling !ire0alls to con!ir& that is the source o! the +roble&. "olution (9 It is also +ossible to recei$e the Check Agents ailed i! the agent con!iguration contains 0orkbenches that are not running4 had 7%' uninstalled or are shutdo0n. An agent encountering co&&unication +roble&s &a, get dela,ed in its +olling 0ork long enough that a su++orted 0orkbench &a, conclude that agent is out o! contact. I! this case is sus+ected re&o$e an, stale 0orkbench in!or&ation !ro& each agentDs con!iguration !ile.

8.3 Process on dri+er terminated "ym tom When ,ou tr, to run a schedule the !ollo0ing error dialog a++ears;

'eaning #hortl, a!ter -a6ordo&o launched the engine execution +rocess on the agent that +rocess ter&inated unex+ectedl,. 'here &a, be &essages ex+laining the reason !or the !ailure in the 0orkbench Error Log. 'his log can be o+ened using +re!erences $ia Windo0 B #ho0 :ie0 B Error Log. At the de!ault log le$el o! WA71I1G all &essages 0ritten to stderr b, the nati$e 6a$a +rogra& on the agent 0ill be sent to the 0orkbench and stored in the Error Log.

"olution () 'he execution +rocess 0ill ter&inate at startu+ i! bad argu&ents are +assed to the @:-. =ere is an exa&+le o! the contents o! the Error Log i! a bad argu&ent is +assed to the @:-;

1ote the @:- co&+laining about an unrecogniAed co&&and line o+tion. In this case exa&ine an, argu&ents s+eci!ied in the 7%'J:-A7G# general +ro+ert, !or the location and ensure there are no t,+os or bogus co&&and line o+tions.

"olution (* Another exa&+le o! a +roble& that +roduces the +rocess ter&inated &essage is i! so&eho0 the 0rong @:- 0as used 0hen launching the engine execution +rocess. =ere is an exa&+le o! 0hat ha++ens i! the agent engine execution is launched 0ith @a$a 1." instead o! the desired @a$a 1.) @:-;

'he a++earance o! :nsu ortedClass;ersion5rror is a clue that the @:- on the agent is not the re<uired I?@a$a 1.) @:-. 'his +roble& could occur i! the 7%' Agent 0as installed in a non>de!ault &anner or i! the installation +ath contained so&e unex+ected characters. =ere are so&e suggested 0orkarounds; 1. 2. 2ninstall and re>install the +roduct. 'ake de!ault $alues !or 0here to install the agent. 2se the en$iron&ent $ariable 7%'J@A:A to ex+licitl, s+eci!, the @a$a executable the agent should launch !or the execution engine. or exa&+le; RPT7<A;A=C>?Program ,iles?-.'?"$P?/dk?bin?/a@a.e%e 'he 6a$a.exe to use should be the I?- @a$a 1.) 6a$a binar, installed 0ith the 7%' Agent. A!ter ,ou set this en$iron&ent $ariable sto+ and restart the -a6ordo&o ser$ice. ro& a co&&and +ro&+t or shell enter the co&&ands belo0; Windows cd +Program ,iles#-.'#"$P#'a/ordomo0 &1A"to &1A"tart cd #o t#-.'#"$P#'a/ordomo .#'$"to .sh .#'$"tart.sh

Unix:

5.

Tips6 Tric&s and 0iscellaneous

5.! Pri+ileges 'he 7ational %er!or&ance 'ester Agent +roduct &ust be installed b, a user 0ith Ad&inistrator +ri$ileges on Windo0s and as root on 2nix. 5.# 0ultiple 'ngines 7n 7ne Agent 0achine %re$ious $ersions o! 7ational %er!or&ance 'ester allo0ed &ulti+le execution engines on one agent &achine. 'he onl, restriction is that the location hostna&es and de+lo,&ent directories &ust be uni<ue. 'his trick also 0orks 0ith the ne0 Load Generation Agent. 7ational %er!or&ance 'ester does not li&it the nu&ber o! engines executing on one agent. 5.3 Locations 'here are no changes related to locations and the Load Generation Agent. I! running using a re&ote agent a location &ust be created and added to the schedule as in +re$ious releases o! 7ational %er!or&ance 'ester. 5.$ Ports 2ith multiple 2or&benches 1ote that i! one agent is su++orting &ulti+le 0orkbenches it is oka, !or the +ort nu&ber to be the sa&e !or e$er, 0orkbench listed in the con!iguration !ile. 5.* 0a( heap %re$ious releases o! 7ational %er!or&ance 'ester re<uired one success!ul execution o! a schedule in order to set the 7%'J*E A2L'J-E-57EJ#IKE +ro+ert, that s+eci!ies the &axi&u& @a$a hea+ !or a location. 'his re<uire&ent

holds !or the ne0 Load Generation Agent. 5n the $er, !irst execution the &ax hea+ 0ill be *9Am4 a hea+ a&ount that 0ill ensure disaster !or a large load test. A custo&er tr,ing to do a large load test straight out o! the box 0ill ha$e agents that ex+erience 5ut5!-e&or,Error and the +rocesses on those agent &a, ter&inate earl,.

5./ 0a8ordomo 'he heart o! the Load Generation Agent is called -a6ordo&o. 5n Windo0s it runs as a ser$ice called -a6ordo&o#er$ice.exe. 5n 2nix it runs as -a6ordo&o. 'he 2nix s,ste&s re<uire custo&er inter$ention i! the, 0ant -a6ordo&o running a!ter a reboot. ?ecause it is a ser$ice4 -a6ordo&o#er$ice.exe should be running auto&aticall, a!ter reboot on Windo0s. 5n Windo0s s,ste&s -a6ordo&o#er$ice 0ill log in!or&ational &essages at startu+ in the s,ste& te&+ director, 0hich is usuall, C;IWindo0sI'e&+I&a6ordo&oser$ice.log. I! there is a +roble&4 +erha+s related to !inding the I?- @:-4 there &a, be &essages in that log that could hel+ deter&ine the cause o! the +roble&. 5.1 0a8ordomo debug flag Eou &a, ha$e noticed there is a debug !lag in the &a6ordo&o.con!ig !ile. I! set to true4 the -a6ordo&o +rocess and an, engine +rocesses launched create log !iles that can be use!ul !or debugging Load Generation Agent launch and +roble&s that occur earl, in schedule execution. Exa&+les o! these !iles are; C;IWindo0sI'e&+I#E7:ICEI&a6ordo&o.log C;IWindo0sI'e&+I#E7:ICEIengineJ=5#'1A-E.log #i&ilar !iles can be !ound on 2nix s,ste&s stored under L'-%L(2#E71A-E.