/
user_manual.tex
2443 lines (1947 loc) · 85.5 KB
/
user_manual.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
%%% user_manual.tex ---
%% Author: Nicolas Niclausse
%% Version: $Id$
\def\RCS$#1: #2 ${\expandafter\def\csname RCS#1\endcsname{#2}}
\RCS$Revision$
\RCS$Date$
\documentclass{TSUNG-en}
\usepackage{shortcuts}
% --------------------------------------------
% Title
% --------------------------------------------
\doctitle{Tsung User's manual}
%\addauthor{Nicolas}{Niclausse}{nicolas.niclausse@niclux.org}
\doccopyright{Nicolas Niclausse.}
\docversion{\RCSRevision}
\docreldate{\RCSDate}
\docref{tsung-user-manual}
\begin{document}
\maketitle
\newpage
\tableofcontents
\section{Introduction}
\subsection{What is Tsung ?}
\program{Tsung} (formerly IDX-Tsunami) is a distributed load testing tool. It is
protocol-independent and can currently be used to stress HTTP, WebDAV, SOAP,
PostgreSQL, MySQL, LDAP, and Jabber/XMPP servers.
It is distributed under the GNU General Public License version 2.
\subsection{What is Erlang and why is it important for Tsung ?}
\program{Tsung's} main strength is its ability to simulate a huge number of
simultaneous user from a single CPU. When used on cluster you can
generate a really impressive load on a server with a modest cluster,
easy to set-up and to maintain.
\program{Tsung} is developed in Erlang and this is where the power
of \program{Tsung} resides.
\par Erlang is a \emph{concurrency-oriented} programming language.
Tsung is based on the Erlang OTP (Open Transaction Platform) and
inherits several characteristics from Erlang:
\begin{itemize}
\item \emph{Performance}: Erlang has been made to support hundred thousands
of lightweight processes in a single virtual machine.
\item \emph{Scalability}: Erlang runtime environment is naturally
distributed, promoting the idea of process's location transparency.
\item \emph{Fault-tolerance}:Erlang has been built to develop robust,
fault-tolerant systems. As such, wrong answer sent from the server
to \program{Tsung} does not make the whole running benchmark crash.
\end{itemize}
More information on Erlang on \url{http://www.erlang.org} and
\url{http://www.erlang-projects.org/}
\subsection{Tsung background}
History:
\begin{itemize}
\item \program{Tsung} development was started by Nicolas Niclausse in
2001 as a distributed jabber load stress tool for internal use at
\url{http://IDEALX.com/}. It has evolved as an open-source
multi-protocol load testing tool several months later. The HTTP
support was added in 2003, and this tool has been used for several
industrial projects. It is now hosted by Erlang-projects, and
supported by \url{http://process-one.net/}. The list of contributors
is available in the source archive
(\url{https://svn.process-one.net/tsung/trunk/CONTRIBUTORS}).
\item It is an industrial strength implementation of a \emph{stochastic model}
for real users simulation. User events distribution is based on a
Poisson Process. More information on this topic in:
Z. Liu, N. Niclausse, and C. Jalpa-Villanueva. \strong{Traffic Model
and Performance Evaluation of Web Servers}. \emph{Performance Evaluation,
Volume 46, Issue 2-3, October 2001}.
\item This model has already been tested in the INRIA \emph{WAGON}
research prototype (Web trAffic GeneratOr and beNchmark). WAGON was
used in the \url{http://www.vthd.org/} project (Very High Broadband
IP/WDM test platform for new generation Internet applications, 2000-2004).
\end{itemize}
\program{Tsung} has been used for very high load tests:
\begin{itemize}
\item \emph{Jabber/XMPP} protocol:
\begin{itemize}
\item 90 000 simultaneous jabber users on a
4-node Tsung cluster (3xSun V240 + 1 Sun V440)
\item 10 000 simultaneous users.
\program{Tsung} was running on a 3-computers cluster (CPU
800MHz)
\end{itemize}
\item \emph{HTTP and HTTPS} protocol:
\begin{itemize}
\item 12 000 simultaneous users.
\program{Tsung} were running on a 4-computers cluster. The
tested platform reached 3 000 requests per second.
\end{itemize}
\end{itemize}
\program{Tsung} has been used at:
\begin{itemize}
\item \emph{DGI} (Direction Générale des impôts): French finance ministry
\item \emph{Cap Gemini Ernst \& Young}
\item \emph{IFP} (Institut Français du Pétrole): French Research Organization
for Petroleum
\item \emph{LibertySurf}
\item Sun\texttrademark for their Mooddlerooms platform on Niagara processors:
\url{http://blogs.sun.com/kevinr/resource/Moodle-Sun-RA.pdf}
\end{itemize}
\section{Features}
\subsection{Tsung main features}
\begin{itemize}
\item \emph{High Performance}: \program{Tsung} can simulate a
huge number of simultaneous users per physical computer: It can
simulates thousands of users on a single CPU (Note: a simulated user
is not always active: it can be idle during a \varname{thinktime}
period). Traditional injection tools can hardly go further than a
few hundreds (Hint: if all you want to do is requesting a single URL
in a loop, use \program{ab}; but if you want to build complex
scenarios with extended reports, \program{Tsung} is for you).
\item \emph{Distributed}: the load can be distributed on a cluster of
client machines
\item \emph{Multi-Protocols} using a plug-in system: HTTP (both standard
web traffic and SOAP), WebDAV, Jabber/XMPP and PostgreSQL are currently
supported. Experimental LDAP and MySQL plugins were included in the 1.3.0 release.
\item \emph{SSL} support
\item \emph{Several IP addresses} can be used on a single machine using
the underlying OS IP Aliasing
\item \emph{OS monitoring} (CPU, memory and network traffic) using Erlang
agents on remote servers or \emph{SNMP}
\item \emph{XML configuration system}: complex user's scenarios are written
in XML. Scenarios can be written with a simple browser using the
Tsung recorder (HTTP and PostgreSQL only).
\item \emph{Dynamic scenarios}: You can get dynamic data from the
server under load (without writing any code) and re-inject it in
subsequent requests. You can also loop, restart or stop a
session when a string (or regexp) matches the server response.
\item \emph{Mixed behaviours}: several sessions can be used to simulate
different type of users during the same benchmark. You can define
the proportion of the various behaviours in the benchmark scenario.
\item \emph{Stochastic processes}: in order to generate a realistic traffic,
user thinktimes and the arrival rate can be randomize using a probability
distribution (currently exponential)
\end{itemize}
\subsection{HTTP related features}
\begin{itemize}
\item HTTP/1.0 and HTTP/1.1 support
\item GET, POST, PUT, DELETE and HEAD requests
\item Cookies: Automatic cookies management
\item \verb|'|GET If-modified since\verb|'| type of request
\item WWW-authentication Basic
\item User Agent support
\item Any HTTP Headers can be added
\item Proxy mode to record sessions using a Web browser
\item SOAP support using the HTTP mode (the SOAPAction HTTP header is
handled).
\item HTTP server or proxy server load testing.
\end{itemize}
\subsection{WEBDAV related features}
The WebDAV (RFC 4918) plugin is a superset of the HTTP plugin. It adds the
following features (some versionning extensions to WebDAV (RFC 3253)
are also supported):
\begin{itemize}
\item Methods implemented: DELETE, CONNECT, PROPFIND, PROPPATCH, COPY,
MOVE, LOCK, UNLOCK, MKCOL, REPORT, OPTIONS, MKACTIVITY, CHECKOUT, MERGE
\item Recording of DEPTH, IF, TIMEOUT OVERWRITE, DESTINATION, URL and
LOCK-TOKEN Headers.
\end{itemize}
\subsection{Jabber/XMPP related features}
\begin{itemize}
\item Authentication (plain-text, digest and sip-digest)
\item presence and register messages
\item Chat messages to online or offline users
\item MUC: join room, send message in room, change nickname
\item Roster set and get requests
\item Global users\verb|'| synchronization can be set on specific actions
\item raw XML messages
\end{itemize}
\subsection{PostgreSQL related features}
\begin{itemize}
\item Basic and MD5 Authentication
\item Basic Queries (Extended queries not yet supported)
\item Proxy mode to record sessions
\end{itemize}
\subsection{MySQL related features}
This plugin is experimental. It works only with MySQL version 4.1 and higher.
\begin{itemize}
\item Secured Authentication method only (MySQL >= 4.1)
\item Basic Queries
\end{itemize}
\subsection{LDAP related features}
This plugin is experimental.
\begin{itemize}
\item bind
\item add, modify and search queries
\item starttls (only with R12B-0 Erlang and up)
\end{itemize}
\subsection{Complete reports set}
Measures and statistics produced by Tsung are extremely feature-full.
They are all represented as a graphic. \program{Tsung} produces
statistics regarding:
\begin{itemize}
\item \emph{Performance}: response time, connection time, decomposition of the user scenario based on request grouping instruction (called \textit{transactions}), requests per second
\item \emph{Errors}: Statistics on page return code to trace errors
\item \emph{Target server behaviour}: An Erlang agent can gather information
from the target server(s). Tsung produces graphs for CPU and memory
consumption and network traffic. SNMP and munin is also supported to
monitor remote servers.
\end{itemize}
\par Note that \program{Tsung} takes care of the synchronization process
by itself. Gathered statistics are «synchronized».
It is possible to generate graphs during the benchmark as statistics
are gathered in real-time.
\subsection{Highlights}
\program{Tsung} has several advantages over other injection tools:
\begin{itemize}
\item \emph{High performance} and \emph{distributed benchmark}: You
can use Tsung to simulate tens of thousands of virtual users.
\item \emph{Ease of use}: The hard work is already done for all supported
protocol. No need to write complex scripts. Dynamic scenarios only
requires small trivial piece of code.
\item \emph{Multi-protocol support}: \program{Tsung} is for example one of
the only tool to benchmark SOAP applications
\item \emph{Monitoring} of the target server(s) to analyze the behaviour
and find bottlenecks. For example, it has been used to analyze cluster
symmetry (is the load properly balanced ?) and to determine the best
combination of machines on the three cluster tiers (Web engine, EJB
engine and database)
\end{itemize}
\section{Installation}
This package has been tested on Linux, FreeBSD and Solaris. A port is
available on MacOS X. It should
work on Erlang supported platforms (Linux, Solaris, *BSD, Win32 and
MacOS-X).
\subsection{Dependencies}
\begin{itemize}
\item Erlang/OTP R10B-0 and up
(\url{http://www.erlang.org/download.html}). Erlang is now
part of fedora and debian/ubuntu repositories.
\item extended regexp module (used for dynamic variables):
gregexp.erl available at
\url{http://www.cellicium.com/erlang/contribs/} . The module is
included in the source and binary distribution of \program{Tsung}. It
is released under the EPL License.
\item pgsql module made by Christian Sunesson (for the PostgreSQL plugin):
sources available at
\url{http://jungerl.sourceforge.net/} . The module is
included in the source and binary distribution of \program{Tsung}. It
is released under the EPL License.
\item mysql module made by Magnus Ahltorp \& Fredrik Thulin (for the mysql plugin):
sources available at
\url{http://www.stacken.kth.se/projekt/yxa/} . The modified module is
included in the source and binary distribution of \program{Tsung}. It
is released under the three-clause BSD License.
\item eldap module (for the LDAP plugin):
sources available at
\url{http://jungerl.sourceforge.net/} . The module is
included in the source and binary distribution of \program{Tsung}. It
is released under the GPL License.
\item mochiweb libs (for xpath parsing, optionally used for dynamic variables in
the HTTP plugin):
sources available at
\url{http://code.google.com/p/mochiweb/} . The module is
included in the source and binary distribution of \program{Tsung}. It
is released under the MIT License.
\item gnuplot and perl5 (optional; for graphical output with
\command{tsung\_stats.pl} script). The Template Toolkit is used for HTML
reports (see \url{http://template-toolkit.org/})
\item python and mathplotlib (optional; for graphical output with
\command{tsung-plotter}).
\item for distributed tests, you need an ssh access to remote
machines without password (use a RSA/DSA key without pass-phrase or
ssh-agent) (rsh is also supported)
\item bash
\end{itemize}
\subsection{Compilation}
\begin{Verbatim}
./configure
make
make install
\end{Verbatim}
\subsection{Configuration}
The default configuration file is \file{~/.tsung/tsung.xml} (
there are several sample files in
\file{/usr/share/doc/tsung/examples}).
Log files are saved in \file{~/.tsung/log/} . A new sub-directory
is created for each test using the current date as name
(\file{~/.tsung/log/20040217-09:40} for ex.)
\subsection{Running}
Two commands are installed in the directory \varname{\$PREFIX/bin}:
\command{tsung} and \command{tsung-recorder}. A man page is available
for both commands.
\begin{Verbatim}
>tsung -h
Usage: tsung <options> start|stop|debug|status
Options:
-f <file> set configuration file (default is ~/.tsung/tsung.xml)
-l <logfile> set log file (default is ~/.tsung/log/tsung.log)
-i <id> set controller id (default is empty)
-r <command> set remote connector (default is ssh)
-F use long names (FQDN) for erlang nodes
-v print version information and exit
-h display this help and exit
\end{Verbatim}
A typical way of using tsung is to run:
\command{tsung -f myconfigfile.xml start}.
The command will print the current log directory created for the test, and wait until the test is
over.
\subsection{Feedback}
Use the Tsung mailing list (see
\url{https://lists.process-one.net/mailman/listinfo/tsung-users}) if you have
suggestions or questions about \program{Tsung}. You can also use the
bug-tracker available at \url{https://support.process-one.net/browse/TSUN}.
You can also try the \#tsung IRC channel on Freenode.
\section{Benchmark approach}
\subsection{HTTP/WebDAV benchmark approach}
\subsubsection{Benchmarking a Web server}
\begin{enumerate}
\item Record one or more sessions: start the recorder with:
\command{tsung-recorder start}, and then configure your browser to use Tsung
proxy recorder (the listen port is 8090). A session file will be
created. For HTTPS recording, use \userinput{http://ssl-} instead of
\userinput{https://} in your browser.
\item Edit / organize scenario, by adding recorded sessions in the
configuration file.
\item Write small code for dynamic parts if needed and place dynamic mark-up
in the scenario.
\item Test and adjust scenario to have a nice progression of the load. This
is highly dependent of the application and of the size of the target
server(s). Calculate the normal duration of the scenario and use the
interarrival time between users and the duration of the phase to estimate
the number of simultaneous users for each given phase.
\item Launch benchmark with your first application parameters set-up:
\command{tsung start} (run \command{man tsung} for more options)
\item Wait for the end of the test or stop by hand with
\command{tsung stop} (reports can also be generated during the
test (see § \ref{sec:statistics-reports}) : the statistics are
updated every 10 seconds). For a brief summary of the current
activity, use \command{tsung status}
\item Analyze results, change parameters and relaunch another benchmark
\end{enumerate}
\subsubsection{WEBDAV }
It's the same approach as HTTP: first you start to record one or more
sessions with the recorder:
\command{tsung-recorder -p webdav start}
\subsubsection{Benchmarking a proxy server}
By default, the HTTP plugin is used to benchmark HTTP servers. But you
can also benchmark HTTP Proxy servers. To do that, you must add in the
\varname{options} section:
\begin{Verbatim}
<option type="ts_http" name="http_use_server_as_proxy" value="true"></option>
\end{Verbatim}
\subsection{LDAP benchmark approach}
An LDAP plugin for the recorder is not yet implemented, so you have to
write the session by yourself; see section \ref{sec:session:ldap} for
more information.
\subsection{PostgreSQL benchmark approach}
It's the same approach as HTTP: first you start to record one or more
sessions with the recorder:
\command{tsung-recorder -p pgsql start}
This will start a proxy listening to port 8090 and will proxy requests
to 127.0.0.0:5432.
To choose another port and/or address:
\command{tsung-recorder -L 5432 -I 10.6.1.1 -P 5433 -p pgsql start}
This will start a proxy listening to port 5432 and will proxy requests
to 10.6.1.1:5433.
\subsection{MySQL benchmark approach}
A MySQL plugin for the recorder is not yet implemented, so you have to
write the session by yourself; see section \ref{sec:session:mysql} for
more information.
\subsection{Jabber/XMPP benchmark approach}
\subsubsection{Overview}
This paragraph explains how to write a session for Jabber/XMPP.
There are two differences between HTTP and Jabber testing:
\begin{enumerate}
\item There is no recorder for Jabber, so you have to write your
sessions by hand (an example is provided in
\ref{sec:sessions:jabber}).
\item the jabber plugin does not parse XML; instead it uses packet
acknowledgments.
\end{enumerate}
\subsubsection{Acknowledgments of messages}
Since the jabber plugin does not parse XML (historically, it was for
performance reasons), you must have a way to tell when a request is
finished. There are 3 possibilities:
\begin{description}
\item[ack=local] as soon as a packet is received from the server, the
request is considered as completed. Hence if you use a local ack with a request
that do not require a response from the server (presence for ex.), it
will wait forever (or until a timeout is reached).
\item[ack=no\_ack] as soon as the request is send, it is considered as completed (do
not wait for incoming data)
\item[ack=global] synchronized users. its main use is for waiting for all
users to connect before sending messages. To do that, set a request
with global ack (it can be the first presence msg:
\begin{Verbatim}
<request> <jabber type="presence" ack="global"/> </request>
\end{Verbatim}
You also have to specify the number of users to be connected:
\begin{Verbatim}
<option type="ts_jabber" name="global_number" value="100"></option>
\end{Verbatim}
To be sure that exactly \varname{global\_number} users are started, add the
\userinput{'maxnumber'} attribute to \varname{'users'}
\begin{Verbatim}
<users maxnumber="100" interarrival="1.0" unit="second"></users>
\end{Verbatim}
If you do not specify \varname{maxnumber}, the global ack will be reset every
\varname{global\_number} users
\end{description}
\label{bidi:presence}
\strong{New in 1.2.2:} This version adds an new option for a
session. if you set the attribute \varname{bidi} (for bidirectional)
in the \varname{session} tag: \userinput{<session ... bidi='true'>},
then incoming messages from the server will be analyzed. Currently,
only roster subscription requests are handled: if a user received a
subscription request (\userinput{<presence ... type='subscribe'>}), it
will respond with a \userinput{<presence ... type='subscribed'>}
message.
\subsubsection{Status: Offline, Connected and Online}
You can send messages to offline or online users. A user is considered
online when he has send a \userinput{presence:initial} message (before
this message , the state of the user is \varname{connected}).
If you want to switch back to \varname{connected} before going
\varname{offline}, you can use a \userinput{presence:final} message:
\userinput{presence:final} does two things:
\begin{enumerate}
\item It removes the client from the list of Online users, and moves
them into the list of Connected users.
\item It sends a broadcast presence update of type='unavailable'.
\end{enumerate}
\userinput{presence:final} is optional.
\emph{warn:} this is new in \strong{1.2.0}, in earlier version, only 2
status were available: online and offline; a user was considered
online as soon as it was connected.
\subsubsection{Authentication}
Below are configuration examples for the possible authentication
methods. Note: the regular expressions used here are only examples -
they may need to be altered depending on how a particular server
implementation composes messages (see also ~\ref{sec:jabber-options}
for password settings).
\begin{itemize}
\item \strong{plain authentication} - sends clear-text passwords:
\begin{Verbatim}
<session probability="100" name="jabber-plain" type="ts_jabber">
<request> <jabber type="connect" ack="local"></jabber> </request>
<thinktime value="2"></thinktime>
<transaction name="auth_plain">
<request> <jabber type="auth_get" ack="local"></jabber> </request>
<request> <jabber type="auth_set_plain" ack="local"></jabber> </request>
</transaction>
...
</session>
\end{Verbatim}
\item \strong{digest authentication} as described in XMPP JEP-0078: Non-SASL Authentication
\url{http://www.jabber.org/jeps/jep-0078.html}
\begin{Verbatim}
<session probability="100" name="jabber-digest" type="ts_jabber">
<!-- regexp captures stream ID returned by server -->
<request>
<dyn_variable name="sid" regexp="<stream:stream id="\(.*\)" xmlns:stream"/>
<jabber type="connect" ack="local"></jabber>
</request>
<thinktime value="2"></thinktime>
<transaction name="auth_digest">
<request> <jabber type="auth_get" ack="local"></jabber> </request>
<request subst='true'> <jabber type="auth_set_digest" ack="local"></jabber> </request>
</transaction>
...
</session>
\end{Verbatim}
\item \strong{sip-digest authentication}
\begin{Verbatim}
<session probability="100" name="jabber-sipdigest" type="ts_jabber">
<request> <jabber type="connect" ack="local"></jabber> </request>
<thinktime value="2"></thinktime>
<transaction name="auth_sipdigest">
<!-- regexp captures nonce value returned by server -->
<request>
<dyn_variable name="nonce"
regexp="<Nonce encoding="hex">\(.*\)<\/Nonce>"/>
<jabber type="auth_get" ack="local"></jabber>
</request>
<request subst='true'> <jabber type="auth_set_sip" ack="local"></jabber> </request>
</transaction>
...
</session>
\end{Verbatim}
\end{itemize}
\section{Using the proxy recorder}
The recorder has three plugins: for HTTP, WebDAV and for PostgreSQL.
To start it, run \command{tsung-recorder -p <PLUGIN> start}, where \varname{PLUGIN} can be
\userinput{http}, \userinput{webdav} or \userinput{pgsql} for PostgreSQL. The default plugin is \userinput{http}.
The proxy is listening to port 8090. You can change the port with
\userinput{-L portnumber}.
To stop it, use \command{tsung-recorder stop}.
The recorded session is created as
\file{~/.tsung/tsung_recorderYYYMMDD-HH:MM.xml}; if it doesn't work,
take a look at \file{~/.tsung/log/tsung.log-tsung_recorder@hostname}
During the recording, you can add custom tag in the XML file, this can
be useful to set transactions or comments:
\command{tsung-recorder record\_tag "<transaction name='login'>''}
Once a session has been created, you can insert it in your main configuration
file, either by editing by hand the file, or by using an ENTITY
declaration, like:
\begin{Verbatim}
<!DOCTYPE tsung SYSTEM "/usr/share/tsung/tsung-1.0.dtd" [
<!ENTITY mysession1 SYSTEM "/home/nniclausse/.tsung/tsung_recorder20051217-13:11.xml">
]>
...
<sessions>
&mysession1;
</sessions>
\end{Verbatim}
\subsection{PostgreSQL}
For PostgreSQL, the proxy will connect to the server at IP 127.0.0.1
and port 5432. Use \userinput{-I serverIP} to change the IP and
\userinput{-P portnumber} to change the port.
\subsection{HTTP and WEBDAV}
For HTTPS recording, use \userinput{http://ssl-} instead of
\userinput{https://} in your browser
\strong{New in 1.2.2}: For HTTP, you can configure the recorder to
use a parent proxy (but this will not work for https). Add the -u
option to enable parent proxy, and use \userinput{-I serverIP} to set
the IP and \userinput{-P portnumber} to set the port of the parent.
\section{Understanding tsung.xml configuration file}
The default encoding is utf-8. You can use a different encoding, like in:
\begin{Verbatim}
<?xml version="1.0" encoding="ISO-8859-1"?>
\end{Verbatim}
\subsection{File structure}
Scenarios are enclosed into Tsung tags:
\begin{Verbatim}
<?xml version="1.0"?>
<!DOCTYPE tsung SYSTEM "/usr/share/tsung/tsung-1.0.dtd" [] >
<tsung loglevel="info">
...
</tsung>
\end{Verbatim}
If you add the attribute \userinput{dumptraffic="true"}, all the
traffic will be logged to a file. \emph{Warn:} this will considerably
slow down Tsung, so use with care. It is useful for debugging
purpose. You can use the attribute \userinput{dumptraffic="light"} to
dump only the first 44 bytes.
The \varname{loglevel} can also have a great impact on performance:
For high load, \userinput{warning} is recommended.
Possible values are:
\begin{itemize}
\item emergency
\item critical
\item error
\item warning
\item notice (default)
\item info
\item debug
\end{itemize}
For REALLY verbose logging, recompile tsung with \command{make debug}
and set \varname{loglevel} to \userinput{debug}.
\subsection{Clients and server}
Scenarios start with clients (Tsung cluster) and server definitions:
For non distributed load, you can use a basic setup like:
\begin{Verbatim}
<clients>
<client host="localhost" use_controller_vm="true"/>
</clients>
<servers>
<server host="192.168.1.1" port="80" type="tcp"></server>
</servers>
\end{Verbatim}
This will start the load on the same host and on the same Erlang
virtual machine as the controller.
The server is the entry point into the cluster (\strong{New in 1.2.0:}
if several servers are defined, a round robin algorithm is used to
choose the server).
The next example is more complex, and use several features for
advanced distributed testing:
\begin{Verbatim}
<clients>
<client host="louxor" weight="1" maxusers="800">
<ip value="10.9.195.12"></ip>
<ip value="10.9.195.13"></ip>
</client>
<client host="memphis" weight="3" maxusers="600" cpu="2"/>
</clients>
<servers>
<server host="10.9.195.1" port="8080" type="tcp"></server>
</servers>
\end{Verbatim}
Several virtual IP can be used to simulate more machines. This is
very useful when a load-balancer use the client\verb|'|s IP to
distribute the traffic among a cluster of servers. \strong{New in
1.1.1:} IP is no longer mandatory. If not specified, the default IP will
be used.
In this example, a second machine is used in the Tsung cluster,
with a higher weight, and 2 cpus. Two Erlang virtual machines will be
used to take advantage of the number of CPU.
\begin{quote}
\strong{Note:} Even if an Erlang VM is now able to handle severals CPUs
(erlang SMP), benchmarks shows that it's more efficient to use one VM
per CPU (with SMP disabled) for tsung clients. Only the controller node is using SMP
erlang. Therefore, you cpu should be equal to the number of cores of
your nodes.
\end{quote}
By default, the load is distributed uniformly on all CPU (one cpu
per client by default). The weight parameter (integer) can be used to
take into account the speed of the client machine. For instance, if
one real client has a weight of 1 and the other client has a weight
of 2, the second one will start twice the number of users as the
first (the proportions will be 1/3 and 2/3). In the earlier example
where for the second client has 2 CPU and weight=3, the weight is
equal to 1.5 for each CPU.
The \varname{maxusers} parameter is used to bypass the limit of
maximum number of sockets opened by a single process (usually 1024)
and the lack of scalability of the \varname{select} system call. When
the number of users is higher than the limit, a new erlang virtual
machine will be started to handle new users. The default value of
\varname{maxusers} is 800 . Nowadays, with kernel polling enable, you
can and should use a very large value for \varname{maxusers} (30000 for example) without
performance penalty (but don't forget to raise the limit of the OS with
\command{ulimit -n}, see also FAQ \ref{sec:faq:emfile}).
\subsection{Monitoring}
Tsung is able to monitor remote servers using several backends that
communicates with remote agent; This
is configured in the \varname{<monitoring>} section. Available
statistics are: cpu activity, load average, memory usage.
Several types of remote agents are supported (\userinput{erlang} is the default) :
\subsubsection{Erlang}
The remote agent is started by Tsung. It use erlang communications to
retrieve statistics of activity on the server. For example, here is a
cluster monitoring definition based on Erlang agents, for a cluster of
6 computers:
\begin{Verbatim}
<monitoring>
<monitor host="geronimo" type="erlang"></monitor>
<monitor host="bigfoot-1" type="erlang"></monitor>
<monitor host="bigfoot-2" type="erlang"></monitor>
<monitor host="f14-1" type="erlang"></monitor>
<monitor host="f14-2" type="erlang"></monitor>
<monitor host="db" type="erlang"></monitor>
</monitoring>
\end{Verbatim}
Note: monitored computers needs to be
accessible through the network, and erlang communications must be
allowed (no firewall is better ). SSH (or rsh) needs to be configured to
allow connection without password on. \strong{You must use the same
version of Erlang/OTP on all nodes otherwise it may not work
properly !}
If you can't have erlang installed on remote servers, you can use one
of the other available agents:
\subsubsection{SNMP}
The type keyword \userinput{snmp} can replace the erlang keyword, if SNMP monitoring
is preferred. They can be mixed. Since version 1.2.2, you can customize the SNMP version,
community and port number. It uses the MIB provided in
\program{net-snmp} (see also \ref{sec:faq:snmp}).
\begin{Verbatim}
<monitoring>
<monitor host="geronimo" type="snmp"/>
<monitor host="f14-2" type="erlang"></monitor>
<monitor host="db" type="snmp">
<snmp version="v2" community="mycommunity" port="11161"/>
</monitor>
</monitoring>
\end{Verbatim}
The default version is \userinput{v1}, default community
\userinput{public} and default port \userinput{161}.
\subsubsection{Munin}
Since version \strong{1.3.1}, Tsung is able to retrieve data from a munin-node agent
(see \url{http://munin.projects.linpro.no/wiki/munin-node}). The \varname{type}
keyword must be set to \userinput{munin}, for example:
\begin{Verbatim}
<monitoring>
<monitor host="geronimo" type="munin"/>
<monitor host="f14-2" type="erlang"></monitor>
</monitoring>
\end{Verbatim}
\subsection{Defining the load progression}
\subsubsection{Randomly generated users}
The load progression is set-up by defining several arrival phases:
\begin{Verbatim}
<load>
<arrivalphase phase="1" duration="10" unit="minute">
<users interarrival="2" unit="second"></users>
</arrivalphase>
<arrivalphase phase="2" duration="10" unit="minute">
<users interarrival="1" unit="second"></users>
</arrivalphase>
<arrivalphase phase="3" duration="10" unit="minute">
<users interarrival="0.1" unit="second"></users>
</arrivalphase>
</load>
\end{Verbatim}
With this setup, during the first 10 minutes of the test, a new user
will be created every 2 seconds, then during the next 10 minutes, a
new user will be created every second, and for the last 10 minutes,
10 users will be generated every second. The test will finish when
all users have ended their session.
The complete sequence can be executed several times using the
\varname{loop} attribute in the \varname{load} tag
(\userinput{loop='2'} means the sequence will be looped twice, so the
complete load will be executed 3 times) (feature available since
version 1.2.2).
The load generated in terms of HTTP requests / seconds will also
depend on the mean number of requests within a session (if you have a
mean value of 100 requests per session and 10 new users per seconds,
the theoretical average throughput will be 1000 requests/ sec).
\subsubsection{Statically generated users}
If you want to start a given session (see ~\ref{sec:sessions}) at a given time during the test,
it is possible since version \strong{1.3.1}:
\begin{Verbatim}
<load>
<arrivalphase phase="1" duration="10" unit="minute">
<users interarrival="2" unit="second"></users>
</arrivalphase>
<user session="http-example" start_time="185" unit="second"></users>
<user session="http-example" start_time="10" unit="minute"></users>
<user session="foo" start_time="11" unit="minute"></users>
</load>
<sessions>
<session name="http-example" probability="0" type="ts_http">
<request> <http url="/" method="GET"></http> </request>
</session>
<session name="foo" probability="100" type="ts_http">
<request> <http url="/" method="GET"></http> </request>
</session>
<sessions>
\end{Verbatim}
In this example, we have two sessions, one has a "0" probability (and
therefore will not be used in the first phase), and the other
100\%. We define 3 users starting respectively 3mn and 5 seconds
after the beginning of the test (using the \userinput{http-example}
session), one starting after 10 minutes, and a last one starting after
11 minutes (using the \userinput{foo} session this time)
\subsection{Setting options}
\par Default values can be set-up globally: \varname{thinktime} between requests
in the scenario, ssl cipher algorithms, TCP/UDP buffer sizes (the default
value is 32KB). These values overrides
those set in session configuration tags if override is true.
\begin{Verbatim}
<option name="thinktime" value="3" random="false" override="true"/>
<option name="ssl_ciphers"
value="EXP1024-RC4-SHA,EDH-RSA-DES-CBC3-SHA"/>
<option name="tcp_snd_buffer" value="16384"></option>
<option name="tcp_rcv_buffer" value="16384"></option>
<option name="udp_snd_buffer" value="16384"></option>
<option name="udp_rcv_buffer" value="16384"></option>
\end{Verbatim}
A new option is available in version \strong{1.3.1}: hibernate. This
is used to reduced memory consumption of simulated users during
thinktimes. By default, hibernation will be activated for thinktimes
higher than 10sec. This value can be changed like this:
\begin{Verbatim}
<option name="hibernate" value="5"></option>
\end{Verbatim}
To disable hibernation, you must set the value to \userinput{infinity}.
\subsubsection{Jabber options}
\label{sec:jabber-options}
Default values for specific protocols can be defined. Here is an
example of option values for Jabber/XMPP:
\begin{Verbatim}
<option type="ts_jabber" name="global_number" value="5" />
<option type="ts_jabber" name="userid_max" value="100" />
<option type="ts_jabber" name="domain" value="jabber.org" />
<option type="ts_jabber" name="username" value="myuser" />
<option type="ts_jabber" name="passwd" value="mypasswd" />
<option type="ts_jabber" name="muc_service" value="conference.localhost"/>
\end{Verbatim}
Using these values, users will be \userinput{myuserXXX} where XXX is an integer in
the interval [1:userid\_max] and passwd \userinput{mypasswdXXX}
If not set in the configuration file, the values will be set to:
\begin{itemize}
\item global\_number = 10000
\item userid\_max = 100
\item domain = erlang-projects.org
\item username = tsunguser
\item passwd = sesame
\end{itemize}
You can also set the \varname{muc\_service} here (see previous example).
\subsubsection{HTTP options}
For HTTP, you can set the \varname{UserAgent} values
(\strong{available since Tsung 1.1.0}), using a probability for each
value (the sum of all probabilities must be equal to 100)
\begin{Verbatim}
<option type="ts_http" name="user_agent">
<user_agent probability="80">
Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7.8) Gecko/20050513 Galeon/1.3.21
</user_agent>
<user_agent probability="20">
Mozilla/5.0 (Windows; U; Windows NT 5.2; fr-FR; rv:1.7.8) Gecko/20050511 Firefox/1.0.4
</user_agent>
</option>
\end{Verbatim}
\subsection{Sessions}
\label{sec:sessions}
Sessions define the content of the scenario itself. They describe
the requests to execute.
Each session has a given probability. This is used to decide which
session a new user will execute. The sum of all session\verb|'|s
probabilities must be 100.