# $Id$

  IDX-TSUNAMI LISEZMOI
  IDEALX

  ____________________________________________________________

  Table des matires


  1. Introduction

     1.1 Gnralits
     1.2 Qu'est-ce que ce logiciel fait?

  2. Installation

     2.1 Dpendances
     2.2 Compilation et Installation
     2.3 Problmes/Bugs
     2.4 Portabilit

  ____________________________________________________________

  1.  Introduction

  1.1.  Gnralits

  Ce document donne un rapide descriptifs de IDX-TSUNAMI, qui est
  distribu sous les termes de la GNU General Public License version 2
  (voir le fichier COPYING).

  1.2.  Qu'est-ce que ce logiciel fait?

  Le propos de IDX-TSUNAMI est de simuler des utilisateurs afin de
  tester la monte en charge et les performances d'applications
  client/serveur (bases sur IP). Actuellement, les protocoles
  HTTP et Jabber sont implments, et IDX-TSUNAMI est trs facilement
  extensible (voir le fichier doc/Design.txt pour une description
  de l'implmentation et des possibilits d'extensions). IDX-TSUNAMI
  utilise le langage Erlang.

  Ce logiciel est capable de simuler plusieurs milliers d'utilisateurs
  simultanment, et ceux-ci peuvent tre rpartis sur plusieurs
  machines. Plus de 10000 utilisateurs peuvent tre simuls sur une
  seule machine; la limite suprieure dpend du type de hardware et
  galement de l'activit des clients simuls.

  L'ide est de simuler le comportement d'un client rel en utilisant
  un modle de type stochastique, ceci afin de reproduire le trafic
  plus fidlement que peuvent le faire de simple modles dterministes.

  Un utilisateur est caractris par une une suite d'actions
  (requetes, thinktime) faites au cours d'une session. Plusieurs
  sessions peuvent tre dfinies, chacune avec une popularit
  donne. De cette faon, lors de l'injection, chaque nouvel
  utilisateur utilisera un type de session en tirant alatoirement une
  session (en fonction de la popularit de chaque session).

  Un paramtre important est le l'inter-arrive des clients qui
  dtermine le taux d'arrive des clients sur le systme (ie. le
  nombre de clients arrivant sur le systme -- dmarrant leur session -- par
  unit de temps). Plusieurs phases peuvent tre dfinies pour un
  tests, chaque phase injectant des utilisateurs  un taux donn.

  Dans l'implmentation actuelle, la taux d'arrive des clients et le
  temps entre message d'un mme client ("think time") sont modliss
  par une distribution exponentielle (par consquent, le processus
  d'arrive est un processus de Poisson).

  Le trafic peut tre "dump" dans un fichier, afin de pouvoir
  effectuer toutes sortes d'analyse aprs coup (option 'dumptrafic'
  dans le fichier de configuration XML). Attention, cette option peux
  ralentir considrablement les injecteurs en cas de trs forte
  charge.

  Voir galement le site  http://tsunami.idealx.org/

  NEW: Un manuel utilisateur est maintenant disponible:
  http://tsunami.idealx.org/user_manual.htm (en anglais seulement pour
  le moment)

  2.  Installation

  2.1.  Dpendances
  
  - ncessite Erlang/OTP R9C-0 (http://www.erlang.org/download.html)

  - xmerl-0.19 (http://sowap.sourceforge.net/download.html). Un paque
    debian binaire est disponible  l'adresse 
    http://tsunami.idealx.org/dist/

    xmerl-0.15 devrait fonctionner, mais la notation <tag/> n'est pas
    support par cette version de xmerl (il faut utiliser  la place
    la notation <tag></tag> )

  - le module extended regexp est utilis pour les variables
    dynamiques: gregexp.erl est disponible 
     http://www.cellicium.com/erlang/contribs/ . Ce module est
     inclus dans les distributions sources et binaires de
     IDX-Tsunami. Ce module est diffus en license EPL .

  - gnuplot et perl5 (optionel, utilis pour les sorties graphiques du script 
    analyse_msg.pl). Le Template Toolkit est utilis pour les rapports en HTML
    (cf. http://template-toolkit.org/)
  
  - les tests distribus utilisent un accs ssh non intractif pour
    dmarrer Erlang  distance. Il faut donc utiliser une cl RSA/DSA,
    sans passphrase ou en avec ssh-agent)
	
  2.2.  Compilation et Installation

  ./configure (ceci dtecte l'endroit o erlang est install)
  make
  make install

  Comment l'utiliser:
    1a/ diter un fichier ~/.idx-tsunami/idx-tsunami.xml (toutes les
    options sont dcrites en commentaires dans le fichier d'exemple
    /usr/share/doc/idx-tsunami/examples/idx-tsunami.xml).

    1b/ Lire le fichier doc/Jabber.txt pour des informations spcifiques  
    Jabber.

    2/ utilisez le script "idx-tsunami --start" pour dmarrer le 
    test de charge (man idx-tsunami pour avoir les options disponibles)

    3/ Lorsque c'est termin (idx-tsunami --stop pour forcer l'arrt), le
    script analyse_msg.pl (/usr/lib/idx-tsunami/bin/analyse_msg.pl)
    gnre une synthse des temps de rponses;
    ce script peut galement gnrer des graphes avec l'option --plot.

 	   Depuis la version 0.2.0, les statistique peuvent tre calculs
 	   en temps rel (mise  jour toutes les 10 secondes par dfaut)
 	   avec les options --stats and --plot option. Le script va
 	   gnrer des graphes au format postscript en utilisant
 	   gnuplot. L'option --stats requiert en argement le nomdu fichier
 	   de log, par dfaut 'idx-tsunami.log-YYYY:MM:DD-HH:mm'
		   
	   Les mesures suivantes sont disponibles:
		- response_time (temps de rponse pour chaque requte)
		- page_resptime (response time pour chaque ensemble de requte)
		- connect (dure pour effectuer la connexion)
		- reconnect (nombre de reconnexion)
		- size (taille des rponses)
		- session (dure d'une session)
		- users (nombre d'utilisateurs simultans)

       mesures spcifiques  HTTP :
		  - un compteur pour chaque type de rponse (200, 404, etc.)
  
       Depuis la version v1.0.beta1, il est possible de customiser
       les mesures en dfinissant des "transactions" dans les
       sessions. L'option --extra est ncessaire pour afficher les
       statistiques os_mon (cpu, mmoire libre)

       Depuis la version v1.0.beta3, un rapport HTML peut tre gnrer
       en utilisant l'option --html. Ceci utilise le Template
       Toolkit. Le rpertoire contenenant les templates est
       ~/idx-tsunami/templates ou /usr/share/idx-tsunami/template ou
       encore peut tre configur par --tdir <dir>
 
      Ex: > cd ~/.idx-tsunami/log/2004YYYY-XX:XX
          > analyse_msg.pl --stats idx-tsunami.log --plot --html

    4/ Pour utiliser le proxy enregistreur de sessions HTTP depuis un
    navigateur, il faut d'abord dmarrer le proxy avec la commande
    'idx-tsunami recorder'. Celui-ci dmmare le proxy qui coute sur le
    port 8090. Il suffit ensuite de paramtrer le navigateur pour
    utiliser ce proxy. Toutes les requtes et les 'thinktimes' seront
    enregistres dans un fichier directement au format XML. Une fois
    termin, lancer la commande 'idx-tsunami stop_recorder'.



  2.3.  Problmes/Bugs
 
    Envoyez vos questions/rapports de bugs  nicolas.niclausse@IDEALX.com
 
    Ou bien abonnez vous  la liste de diffusion
       http://lists.idealx.org/info/idx-tsunami

  2.4.  Portabilit

    Ce logiciel n'a t test que sous Linux. Il devrait nanmoins
    fonctionner sous toute plate-forme support par Erlang (Solaris et
    FreeBSD en particulier).



