<commit_before>Usage
-----

So, you've installed Yandex.Tank to a proper machine, it is close to target,
access is permitted and server is tuned. How to make a test?

First Steps
~~~~~~~~~~~

Create a file on a server with Yandex.Tank: **load.ini**

::

  [phantom]
  address=203.0.113.1 ;Target's address
  port=80 ;target's port
  rps_schedule=line(1, 100, 10m) ;load scheme

Yandex.Tank have 3 primitives for describing load scheme: 

1. ``step (a,b,step,dur)`` makes stepped load, where a,b are start/end load
values, step - increment value, dur - step duration. 

2. ``line (a,b,dur)`` makes linear load, where ``a,b`` are start/end load, ``dur``
- the time for linear load increase from a to b. 

3. ``const (load,dur)`` makes constant load. ``load`` - rps amount, ``dur`` - load duration. You can set
fractional load like this: ``line(1.1, 2.5, 10)`` -- from 1.1rps to 2.5 for 10 seconds. Note: ``const(0, 10)`` - 0 rps for 10 seconds, in fact 10s pause
in a test.

``step`` and ``line`` could be used with increasing and decreasing
intensity: 

* ``step(25, 5, 5, 60)`` - stepped load from 25 to 5 rps, with 5 rps steps, 
  step duration 60s. ``step(5, 25, 5, 60)`` - stepped load from 5 to 25 rps, 
  with 5 rps steps, step duration 60s

* ``line(100, 1, 10m)`` - linear load from 100 to 1 rps, duration - 10
  minutes ``line(1, 100, 10m)`` - linear load from 1 to 100 rps, duration
  - 10 minutes

You can specify complex load schemes using those primitives, for example: ``rps_schedule=line(1,10,10m) const(10,10m)`` - linear load from 1 to 10, duration 10 mins and then 10 mins of 10 RPS constant load.

Time duration could be defined in seconds, minutes (m) and hours (h).
For example: ``27h103m645``

For a test with constant load at 10rps for 10 minutes, ``load.ini`` should
have next lines:

:: 

  [phantom] 
  address=203.0.113.1 ;Target's address
  port=80 ;target's port. 
  rps_schedule=const(10, 10m) ;load scheme

Voilà, Yandex.Tank setup is done.


Preparing requests
~~~~~~~~~~~~~~~~~~

There are several ways to set up requests: Access mode, URI-style and request-style. 
Regardless of the chosen format, resulted file with requests could be gzipped - tank supports 
archived ammo files.

To specify external ammo file use `ammofile` option. Use `ammo_type` option to explicitly
specify ammo format (if ammo type is uri-style or request-style, tank will try to guess it).

Access mode
''''''''''''
You can use access.log file from your webserver as a source of requests.
Just add to load.ini options `ammo_type=access` and `ammofile=/tmp/access.log` 
where /tmp/access.log is a path to access.log file.

:: 

  [phantom] 
  address=203.0.113.1 ;Target's address
  port=80 ;target's port 
  rps_schedule=const(10, 10m) ;load scheme
  header_http = 1.1 
  headers = [Host: www.target.example.com] 
    [Connection: close] 
  ammofile=/tmp/access.log
  ammo_type=access

Parameter ``headers`` defines headers values (if it nessessary).

URI-style, URIs in load.ini
''''''''''''''''''''''''''''

Update configuration file with HTTP headers and URIs:

:: 

  [phantom] 
  address=203.0.113.1 ;Target's address
  port=80 ;target's port 
  rps_schedule=const(10, 10m) ;load scheme
  ; Headers and URIs for GET requests 
  header_http = 1.1 
  headers = [Host: www.target.example.com] 
    [Connection: close] 
  uris = /   
    /buy   
    /sdfg?sdf=rwerf   
    /sdfbv/swdfvs/ssfsf

Parameter ``uris`` contains uri, which should be used for requests generation.

URI-style, URIs in file
'''''''''''''''''''''''

Create a file with declared requests: **ammo.txt**

::

  [Connection: close] 
  [Host: target.example.com] 
  [Cookies: None] 
  /?drg tag1
  / 
  /buy tag2 
  [Cookies: test]
  /buy/?rt=0&station_to=7&station_from=9

File consist of list of URIs and headers to be added to every request defined below.
Every URI must begin from a new line, with leading ``/``.
Each line that begins from ``[`` is considered as a header.
Headers could be (re)defined in the middle of URIs, as in sample above. I.e  request ``/buy/?rt=0&station_to=7&station_from=9`` will be sent with ``Cookies: test``, not ``Cookies: None``.
Request may be marked by tag, you can specify it with whitespace following URI.

URI+POST-style
''''''''''''''

Create a file with declared requests: **ammo.txt**

::

  [Host: example.org]
  [Connection: close] 
  [User-Agent: Tank]  
  5 /route/?rll=50.262025%2C53.276083~50.056015%2C53.495561&origin=1&simplify=1
  class
  10 /route/?rll=50.262025%2C53.276083~50.056015%2C53.495561&origin=1&simplify=1
  hello!clas
  7 /route/?rll=37.565147%2C55.695758~37.412796%2C55.691454&origin=1&simplify=1
  uripost

File begins with optional lines [...], that contain headers which will
be added to every request. After that section there is a list of URIs and POST bodies.
Each URI line begins with a number which is the size of the following POST body.
Set up ammo type in load.ini:

::

  ammo_type=uripost

Request-style
'''''''''''''

Full requests listed in a separate file. For more complex
requests, like POST, you'll have to create a special file. File format
is:

::

  [size_of_request] [tag]\n
  [request_headers]
  [body_of_request]\r\n
  [size_of_request2] [tag2]\n
  [request2_headers]
  [body_of_request2]\r\n


where ``size_of_request`` – request size in bytes. '\r\n' symbols after
``body`` are ignored and not sent anywhere, but it is required to
include them in a file after each request. '\r' is also required. 

**sample GET requests (null body)**

::

  73 good
  GET / HTTP/1.0
  Host: xxx.tanks.example.com
  User-Agent: xxx (shell 1)
<commit_msg>Update tutorial.rst<commit_after>Usage
-----

So, you've installed Yandex.Tank to a proper machine, it is close to target,
access is permitted and server is tuned. How to make a test?

First Steps
~~~~~~~~~~~

Create a file on a server with Yandex.Tank: **load.ini**

::

  [phantom]
  address=203.0.113.1 ;Target's address
  port=80 ;target's port
  rps_schedule=line(1, 100, 10m) ;load scheme

Yandex.Tank have 3 primitives for describing load scheme: 

1. ``step (a,b,step,dur)`` makes stepped load, where a,b are start/end load
values, step - increment value, dur - step duration. 

2. ``line (a,b,dur)`` makes linear load, where ``a,b`` are start/end load, ``dur``
- the time for linear load increase from a to b. 

3. ``const (load,dur)`` makes constant load. ``load`` - rps amount, ``dur`` - load duration. You can set
fractional load like this: ``line(1.1, 2.5, 10)`` -- from 1.1rps to 2.5 for 10 seconds. Note: ``const(0, 10)`` - 0 rps for 10 seconds, in fact 10s pause
in a test.

``step`` and ``line`` could be used with increasing and decreasing
intensity: 

* ``step(25, 5, 5, 60)`` - stepped load from 25 to 5 rps, with 5 rps steps, 
  step duration 60s. ``step(5, 25, 5, 60)`` - stepped load from 5 to 25 rps, 
  with 5 rps steps, step duration 60s

* ``line(100, 1, 10m)`` - linear load from 100 to 1 rps, duration - 10
  minutes ``line(1, 100, 10m)`` - linear load from 1 to 100 rps, duration
  - 10 minutes

You can specify complex load schemes using those primitives, for example: ``rps_schedule=line(1,10,10m) const(10,10m)`` - linear load from 1 to 10, duration 10 mins and then 10 mins of 10 RPS constant load.

Time duration could be defined in seconds, minutes (m) and hours (h).
For example: ``27h103m645``

For a test with constant load at 10rps for 10 minutes, ``load.ini`` should
have next lines:

:: 

  [phantom] 
  address=203.0.113.1 ;Target's address
  port=80 ;target's port. 
  rps_schedule=const(10, 10m) ;load scheme

Voilà, Yandex.Tank setup is done.


Preparing requests
~~~~~~~~~~~~~~~~~~

There are several ways to set up requests: Access mode, URI-style and request-style. 
Regardless of the chosen format, resulted file with requests could be gzipped - tank supports 
archived ammo files.

To specify external ammo file use `ammofile` option. Use `ammo_type` option to explicitly
specify ammo format (if ammo type is uri-style or request-style, tank will try to guess it).

Access mode
''''''''''''
You can use access.log file from your webserver as a source of requests.
Just add to load.ini options `ammo_type=access` and `ammofile=/tmp/access.log` 
where /tmp/access.log is a path to access.log file.

:: 

  [phantom] 
  address=203.0.113.1 ;Target's address
  port=80 ;target's port 
  rps_schedule=const(10, 10m) ;load scheme
  header_http = 1.1 
  headers = [Host: www.target.example.com] 
    [Connection: close] 
  ammofile=/tmp/access.log
  ammo_type=access

Parameter ``headers`` defines headers values (if it nessessary).

URI-style, URIs in load.ini
''''''''''''''''''''''''''''

Update configuration file with HTTP headers and URIs:

:: 

  [phantom] 
  address=203.0.113.1 ;Target's address
  port=80 ;target's port 
  rps_schedule=const(10, 10m) ;load scheme
  ; Headers and URIs for GET requests 
  header_http = 1.1 
  headers = [Host: www.target.example.com] 
    [Connection: close] 
  uris = /   
    /buy   
    /sdfg?sdf=rwerf   
    /sdfbv/swdfvs/ssfsf

Parameter ``uris`` contains uri, which should be used for requests generation.

URI-style, URIs in file
'''''''''''''''''''''''

Create a file with declared requests: **ammo.txt**

::

  [Connection: close] 
  [Host: target.example.com] 
  [Cookies: None] 
  /?drg tag1
  / 
  /buy tag2 
  [Cookies: test]
  /buy/?rt=0&station_to=7&station_from=9

File consist of list of URIs and headers to be added to every request defined below.
Every URI must begin from a new line, with leading ``/``.
Each line that begins from ``[`` is considered as a header.
Headers could be (re)defined in the middle of URIs, as in sample above. I.e  request ``/buy/?rt=0&station_to=7&station_from=9`` will be sent with ``Cookies: test``, not ``Cookies: None``.
Request may be marked by tag, you can specify it with whitespace following URI.

URI+POST-style
''''''''''''''

Create a file with declared requests: **ammo.txt**

::

  [Host: example.org]
  [Connection: close] 
  [User-Agent: Tank]  
  5 /route/?rll=50.262025%2C53.276083~50.056015%2C53.495561&origin=1&simplify=1
  class
  10 /route/?rll=50.262025%2C53.276083~50.056015%2C53.495561&origin=1&simplify=1
  hello!clas
  7 /route/?rll=37.565147%2C55.695758~37.412796%2C55.691454&origin=1&simplify=1
  uripost

File begins with optional lines [...], that contain headers which will
be added to every request. After that section there is a list of URIs and POST bodies.
Each URI line begins with a number which is the size of the following POST body.
Set up ammo type in load.ini:

::

  ammo_type=uripost

Request-style
'''''''''''''

Full requests listed in a separate file. For more complex
requests, like POST, you'll have to create a special file. File format
is:

::

  [size_of_request] [tag]\n
  [request_headers]
  [body_of_request]\r\n
  [size_of_request2] [tag2]\n
  [request2_headers]
  [body_of_request2]\r\n


where ``size_of_request`` – request size in bytes. '\r\n' symbols after
``body`` are ignored and not sent anywhere, but it is required to
include them in a file after each request. '\r' is also required. 

Parameter ``ammo_type`` is unnecessary, request-style is default ammo type.

**sample GET requests (null body)**

::

  73 good
  GET / HTTP/1.0
  Host: xxx.tanks.example.com
  User-Agent: xxx (shell 1)

{'fraction_non_alphanumeric': 0.1292378507568381, 'fraction_numerical': 0.051872178454456935, 'mean_word_length': 3.838543897216274, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 8, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1499934', 'n_tokens_mistral': 4384, 'n_tokens_neox': 3830, 'n_words': 1442}