tsung.cli.txt

                                  ┏━━━━━━━━━━━┓
                                  ┃   TSUNG   ┃
                                  ┗━━━━━━━━━━━┛

tsung [-f FILE]         #Used to test load on server (1.5.0)
start|stop|debug|status #Send multiple requests from single machine, or by using a cluster of machines.
                        #Can be used on other protocols: HTTP, WEBDAV, XMPP, MySQL, Websocket, AMQP, LDAP
                        #FILE is a xml config (déf: ~/.tsung/tsung.xml), can use - for stdin.
                        #Connection to clients are done using SSH for current OS_USER (must be propertly set up), unless
                        #using -r COMMAND
                        #It takes about 10 seconds to initialize before starting.
-l DIR                  #LOGDIR (déf: ~/.tsung/log/YYYYMMDD-HHMM) where results are written. Stores:
                        #  - tsung.log: main stats about load (step: average of last 10 seconds)
                        #  - tsung_controller@SERVER.log: logs for monitoring of new sessions launches
                        #  - tsungNUM@CLIENT.log: logs of sessions
                        #  - copy of FILE
                        #  - match.log (see below)
-m FILE                 #Use FILE instead of LOGDIR/tsung.log. Can be - for stdout.
-i NUM
-F

-m                      #Different options when using a cluster of computers.

tsung_stats.pl          #Produce a HTML report according to a tsung.log
                        #Located at /usr/lib/tsung/bin/. Must install perl, then install Template package: "cpan Template"
                        #Alternatively, can do <tsung backend="json">, which will produce tsung.log as a JSON file (but can't
                        #use tsung_stats.pl)
                        #If response time crashes, it means it's the limit of load (e.g. requests/sec)
                        #Creates special curves for <transaction>
--stats FILE            #tsung.log to analyze (déf: PWD/tsung.log)
--img_format png|pdf|
ps|svg                  #Déf: png
--dygraph               #Alternative output style

tsplot STR FILE ...     #Same but can compare several tsung.log (FILE). STR is the title.
-c FILE                 #Config file, can use /usr/share/tsung/tsung_plotter/pgsql|http.plots.en.conf
                        #Can customize image type (png or ps), graphs look, or create new/erase graphs.
-d DIR                  #Output dir (déf: /tmp/tsung/)

tsung-recorder          #Create a <session> to include in a tsung xml config (in ~/.tsung/tsung_recorderYYYMMDD-HH:MM.xml) by
[re]start|stop|         #listening to a current session (replicates <request> and <thinktime>)
record_tag STR          #Behaves as a proxy:
                        #  - PostgreSQL: client connects over TCP (not Unix sockets) to tsung-recorder (listening on port 8090
                        #    on current machine)
                        #  - HTTP:
                        #     - connects on http[s]://localhost:8090
                        #     - use -u -l HOST -p PORT to use proxy
                        #  - tsung-recorder forwards to server.
                        #record_tag adds a XML tag STR to the current session.
                        #Can also use pgbadger to do same thing, but from PostgreSQL log files (see pgbadger doc)
-p TYPE                 #TYPE among http (déf), pgsql and webdav.
-L NUM                  #Listening port (déf: 8090)
-l FILE                 #Log file (déf: ~/.tsung/log/tsung.log-tsung_recorder@HOST)

TSUNG XML CONFIG ==>    #
<?xml version="1.0"?>
<!DOCTYPE tsung SYSTEM
"/usr/share/tsung/
tsung-1.0.dtd" [] >     #Opening tags

<tsung>                 #Main tag enclosing all others.
                        #Orders between main tags is strict: follow the order of the doc.
  loglevel=STR          #Between emergency|critical|error|warning(best for high load)|notice(déf)|info|debug.
                        #For tsung_controller and tsungNUM@CLIENT.log files.
                        #Can slow down a lot.
  dumptraffic=STR       #Log binary requests to a LOGDIR/tsung.dump
                        #Can be true (slow), light or protocol (medium, only for http)

<clients>               #Machines sending requests
                        #If several machines, choose randomly according to <client> weight
  <client>              #
    host=STR
    weight=FLOAT        #Déf: 1
    maxusers=NUM        #Specifies the max number of sockets to use before creating a virtual machine to create new socket
                        #slots. On my current machine, OS allow max 1024 sockets (so could put to 800 to be sure).
                        #Can use up to 30000 if raising limit with ulimit -n -S 30000 and ulimit -n -H 30000
    use_controller_vm=
    "true"              #Do it to use VM (good only when CPU == 1)
    cpu=NUM             #Number of cores to use
    batch=STR
    scan_intf=STR       #Options used when using a "batch scheduler" (task scheduler for a cluster of computers)
    <ip>                #Can use several <ip> to simulate several clients with different IP on a single machine.
                        #The number of requests for the machine is same, so it divides the number per virtual client.
                        #Max is 30000 unless using <option name="ports_range" min="1025" max="65535" which doubles it.
                        #Is optional.
      value=IP
      scan="true"       #With value=INTERFACE (e.g. "eth0"), use all the IP available on that interface.

<servers>               #Machines receiving requests.
                        #If several machines, will choose randomly according to <server> weight
  <server>              #
    host=STR
    port=NUM
    type=STR            #Can be tcp[6], upd[6], ssl[6] or websocket (6 is IPv6, other IPv4). Required.
    weight=FLOAT        #Déf: 1

<monitoring>            #Adds stats about clients resource usage stats (CPU, load, memory) to the tsung.log.
                        #Can use localhost, but could also send to another machine using type=STR et different host.
  <monitor>             #
    host=STR
    type=STR            #Protocol to use to transmit to another machine, among:
                        #  - erlang: ssh/rsh must be enabled without password. All Erlang/OTP versions must be same.
                        #  - munin
                        #  - snmp: use <snmp>
    <snmp>              #
      version=STR       #Déf: "v1"
      community=STR     #Déf: "public"
      port=NUM          #Déf: "161"
      <oid>             #
        value=STR
        name=STR
        type=STR        #sample|counter|sum
        eval=STR        #FUNC to apply to VAL (in Erlang)

<load>                  #Progression of the number of new sessions
  loop=NUM              #Execute NUM extra times the whole thing.
  duration=NUM
  unit=STR              #Finishes the <load> even if session are still opened, after NUM STR (e.g. "minute", "second", etc.)
  <arrivalphase>        #Each arrivalphase follows one other, with different duration and frequency of new sessions
                        #(usually increasing)
    phase=NUM           #Order
    duration=NUM
    unit=STR            #How long it lasts.
    <users>             #
      arrivalrate=NUM   #
      unit=STR          #Number of sessions per STR (e.g. "second")
      interarrival=NUM  #Same as arrivalrate, but 1/x
      maxnumber=NUM     #Max no of sessions
  <user>                #Force a specific single session to be launched at a specific point.
    session=STR
    start_time=NUM
    unit=STR

<options>
  <option>              #Different options can be set up, see above when it is mentionned.
    name=STR            #With set_, is local to the current <session>
    value=STR           #With override, local tag attributes redefining options don't have priority.
    override="true"     #Some global options:
                        #  - rate_limit: limit the incoming bandwith (KB/s)
                        #  - thinktime: time between each <request> (déf: 0s). Can use random="true"
                        #  - tcp|udp_snd|rcv_buffer: TCP/UDP buffer sizes in bytes (déf: 32KB)
                        #  - idle|global_ack_timeout: timeout times, in sec. (déf: 10 min. for idle, infinity for global_ack)
                        #  - hibernate: hibernate PC when thinktime is more than NUM sec. (déf: 10)
                        #  - seed: manually set the random seed
                        #HTTP-specific:
                        #  - user_agent: contains probability=INT (0 to 100) with text content being the user agent.
                        #    Def: "tsung"
                        #  - http_use_server_as_proxy: true, to use proxy. Must also set type="ts_http"
                        #HTTPS:
                        #  - certificate: with child:
                        #     <certificate>
                        #       cacertfile=FILE
                        #       keyfile=FILE
                        #       keypass=STR
                        #       certfile=FILE
                        #Websocket:
                        #  - websocket_frame: "text|binary" (def: "binary")
                        #  - websocket_path: PATH

<sessions>              #Ensemble des <session>. Each new session is picked randomly according to its weight.
  <session>             #Scenario (e.g. list of requests).
    name=STR
    weight=NUM          #Mandatory
    type=ts_STR         #Among http, jabber, pgsql, mysql, websocket, amqp, mqtt, ldap.
                        #See online doc for types not documented here.
    <change_type>       #Change type=ts_STR within a session
      new_type=ts_STR
      host=STR
      port=NUM          #Only for specific <client> (optional)
      server_type=STR   #Only for specific <server>
      [re]store="true"  #Save a restore a client state between <change_type>
    <set_option>        #Like <option>, but only for this session.
    <setdynvars>        #Creates a variable that can be used as %%_STR%% in a STR.
                        #The parent <request> or <match> XML tag or text content using STR must have attribute subst="true"
                        #In <pgsql>, text content should not be escape with <![CDATA[...]]>
      <var>
        name=STR        #Only attribute of <var>
      sourcetype=STR    #sourcetype can be:
                        #  - random_number: between start=INT and end=INT
                        #  - random_string: use length=INT
                        #  - file: based on CSV fileid=STR, with delimiter=STR2, each field is attributed to each <var>
                        #     - with order="iter" one line after another for each %%_STR%%
                        #     - or order="random"
                        #  - server: by using <var name="host|port">
                        #  - value: simple constant variable, with value=STR
                        #  - erlang: with code="FUNC" which will call FUNC(PID, DYNDATA), where PID is current one and DYNDATA
                        #    the list of dynamic variables.
    <request>           #*Single* request
      tag=STR           #Makes it possible to exclude the <request> by using tsung -x STR (only Tsung version 1.5.1)
      <http>            #HTTP request with only header Host [C] and User-Agent: tsung [C]
        url=STR         #Path without DOMAIN or, if absolute, URL. Mandatory
        method=STR      #Def: "GET"
        version=FLOAT   #Def: "1.1"
        if_modified_
        since=DATE      #Adds header
        contents[_from_ #Request body (must be percent encoded), with Content-Type "application/x-www-form-urlencoded" [C]
        file]=STR       #If _from_file:
                        #  - takes from a file at path STR
                        #  - percent encode it, and use Content-Type "application/x-www-form-urlencoded" [C] too
        <http_header>   #
          name=STR
          value=STR
        <www_
        authenticate>
          userid=STR
          passwd=STR    #Basic auth
        <www_
        authenticate>
          userid=STR
          passwd=STR
          type="digest" #Digest authentication:
          realm="VAR"   #  - must send first request and catch Header WWW-Authenticate: nonce and realm in <dyn_variable>
          nonce="VAR"   #  - then send second request with www_authenticate using them
        <add_cookie>    #Non persistent cookie
          key=STR
          value=STR
      <pgsql>           #PostgreSQL request
        type=STR        #Among (in order):
                        #  - connect: use also database=STR, username=STR
                        #  - authenticate (don't use if no password): use also password=STR (don't seem to work)
                        #  - sql: text content is the request in <![CDATA[...]]> (to escape it)
                        #  - close
                        #Others: parse, sync, bind, describe, execute for using the SPI (see online doc)
      <websocket>       #Websocket protocol
        type=STR        #Among (in order):
                        #  - connect: use also path=STR (path of the websocket on the <server>)
                        #  - message: use also ack="no_ack" (don't wait for answer), and text content is the message to send
                        #  - close
      <match>           #Do an action when the request response [doesn't] match the text content of <match>, among:
        do=STR          #  - continue|abort
        when=           #  - log: logs request id, user id and name in a log file LOGDIR/match.log
        "[no]match"     #  - dump: dump response in file match-USERID-SESSIONID-REQUESTID-DUMPID.dump
                        #  - restart: restart the <session> (max number of restart: 3)
                        #  - loop: repeat the request after 5 sec. (max number of loops: 20)
                        #In all cases, increments %%_[no]match%%
        skip_headers=
        "TYPE"          #Don't try to match in <TYPE> headers.
        apply_to_
        content=        #Apply Erlang FUNC to request response before trying to match
        "MODULE:FUNC"   #Already usable MODULE:FUNC: ts_digest:md5hex (md5 checksum)
      <dyn_variable>    #Creates %%_STR%% (see <setdynvars>), either:
                        #  - with name, response body STR
                        #  - with header, fetch from response header. If HEADER: VAR=VAL, can use "HEADER/VAR"
                        #  - with re, matching parenthesis in regexp STR (must be HTML-encoded if <http>)
                        #  - with pgsql_expr and <pgsql>, according to response
                        #Can be used in future <request>
        name=STR        #
        header=STR      #
        re=STR          #
        pgsql_expr=
        "data_row
        [ROW_NUMBER].
        COL_VAR"        #
        decode=
        "html_entities" #Perform a HTML decoding before storing the dynamic variable.
      <for>
        from|to=INT
        incr=INT        #Repeat <request> in a for loop.
        var=STR         #Counter is saved as %%_STR%%. Required.
      <repeat>
        name=STR        #Same but for while loop.
        max_repeat=INT  #Last child must be <while|until var=STR [n]eq|gt[e]|lt[e]=INT/> to stop the loop.
      <if>
        var=STR
        [n]eq|gt[e]|
        lt[e]=INT       #Same but for if structure. STR is dynamic variable.
    <thinktime>         #Sleep time
      value=NUM         #Number of seconds
      min|max=NUM
      random="true"     #Use exponential distribution with mean value=NUM, or uniform between min and max.
    <transaction>       #Used in reports: bunch of <request> and/or <thinktime> to get response stats from.
                        #Not SQL transactions, just used by the reports.
      name=STR          #Required


EXAMPLE ==>             #

<?xml version="1.0"?>
<!DOCTYPE tsung SYSTEM "/usr/share/tsung/tsung-1.0.dtd" [] >

<tsung>
  <clients>
    <client host="localhost"></client>
  </clients>
  <servers>
    <server host="localhost" port="80" type="tcp"></server>
  </servers>
  <load>
    <arrivalphase phase="1" duration="10" unit="second">
      <users arrivalrate="1" unit="second"></users>
    </arrivalphase>
  </load>
  <sessions>
    <session name="mys" weight="1" type="ts_http">
      <transaction name="myt">
        <request>
          <http url="/"></http>
        </request>
      </transaction>
    </session>
  </sessions>
</tsung>