-**-c CONFIG, --config=CONFIG** - read options from INI file. It is possible to set multiple INI files by specifying the option serveral times. Default: ``./load.ini``
-**-f, --fail-lock** - don't wait for lock file, quit if it's busy. The default behaviour is to wait for lock file to become free.
-**-l LOG, --log=LOG** - main log file location. Default: ``./tank.log``
-**-n, --no-rc** - don't read ``/etc/yandex-tank/*.ini`` and ``~/.yandex-tank``
-**-o OPTION, --option=OPTION** - set an option from command line. Options set in cmd line override those have been set in configuration files. Multiple times for multiple options. Format: ``<section>.<option>=value`` Example: ``yandex-tank -o "console.short_only=1" --option="phantom.force_stepping=1"``
-**-s SCHEDULED_START, --scheduled-start=SCHEDULED_START** - run test on specified time, date format YYYY-MM-DD hh:mm:ss or hh:mm:ss
-**-q, --quiet** - only print WARNINGs and ERRORs to console
-**-v, --verbose** - print ALL messages to console. Chatty mode
There are 3 ways to constrain requests number: by schedule with **rps_schedule**, by requests number with **ammo_limit** or by loop number with **loop** option. Tank stops if any constrain is reached. If stop reason is reached **ammo_limit** or **loop** it will be mentioned in log file. In test without **rps_schedule** file with requests is used one time by default
Additional options:
***writelog** - enable verbose request/response logging. Available options: 0 - disable, all - all messages, proto_warning - 4хх+5хх+network errors, proto_error - 5хх+network errors. Default: 0
***address** - address of service to test. May contain port divided by colon for IPv4 or DN. For DN, DNS request is performed, and then reverse-DNS request to verify the correctness of name. Default: ``127.0.0.1``
***port** - port of service to test. Default: ``80``
***gatling_ip** - use multiple source addresses. List, divided by spaces.
***phantom_http_entity** - Answer size. Please, keep in mind, especially if your service has large answers, that phantom doesn't read more than defined in ``phantom_http_entity``. Default - 8M
***phantom_stat_*.log** - phantom statistics, aggregated by seconds
***answ_*.log** - detailed request/response log
***phantom_*.log** - internal phantom log
Multi-tests
'''''''''''
To make several simultaneous tests with phantom, add proper amount of sections with names ``phantom-_N_``. All subtests are executed in parallel. Multi-test ends as soon as one subtest stops. Example:
***<modified jmx>** - modified test plan with results output section
***<jmeter_*.jtl>** - JMeter's results
***<jmeter_*.log>** - JMeter's log
BFG
^^^
(`What is BFG <http://en.wikipedia.org/wiki/BFG_(weapon)>`_)
BFG is a generic gun that is able to use different kinds of cannons to shoot. To enable it, disable phantom first, enable BFG plugin and then specify the parameters for BFG and for the cannon you select. For example, if you want to kill an SQL db:
::
[tank]
; Disable phantom:
plugin_phantom=
; Enable BFG instead:
plugin_bfg=Tank/Plugins/BFG.py
; BFG config section:
[bfg]
; gun type -- what kind of gun should BFG use:
gun_type=sql
; what ammo parser should BFG use:
ammo_type=slowlog
; stepper parameters (see phantom options):
instances = 200
ammofile=bsdb03h.sql
rps_schedule=line(1,1000,1m)
loop=500
; selected gun config section:
[sql_gun]
db = mysql://user:user@localhost/
BFG Options
'''''''''''
INI file section: **[bfg]**
***gun_type** - what kind of gun should BFG use
***ammo_type** - what ammo parser should BFG use, default: phantom
* other common stepper options
SQL Gun Options
'''''''''''''''
INI file section: **[sql_gun]**
***db** - DB uri in format: ``dialect+driver://user:password@host/dbname[?key=value..]``, where dialect is a database name such as mysql, oracle, postgresql, etc., and driver the name of a DBAPI, such as psycopg2, pyodbc, cx_oracle, etc. `details <http://docs.sqlalchemy.org/en/rel_0_8/core/engines.html#database-urls>`_
***http** - stop the test if the count of responses in time period (specified) with HTTP codes fitting the mask is larger then the specified absolute or relative value. Examples: ``http(404,10,15) http(5xx, 10%, 1m)``. Exit code - 22
***net** - like ``http``, but for network codes. Use ``xx`` for all non-zero codes. Exit code - 23
***quantile** - stop the test if the specified percentile is larger then specified level for as long as the time period specified. Available percentile values: 25, 50, 75, 80, 90, 95, 98, 99, 100. Example: ``quantile (95,100ms,10s)``
***instances** - available when phantom module is included. Stop the test if instance count is larger then specified value. Example: ``instances(80%, 30) instances(50,1m)``. Exit code - 24
***metric_lower** and **metric_higher** - stop test if monitored metrics are lower/higher than specified for time period. Example: metric_lower(127.0.0.1,Memory_free,500,10). Exit code - 31 and 32. **Note**: metric names (except customs) are written with underline. For hostnames masks are allowed (i.e target-\*.load.net)
Basic criteria aren't aggregated, they are tested for each second in specified period. For example autostop=time(50,15) means "stop if average responce time for every second in 15s interval is higher than 50ms"
***total_time** — like ``time``, but accumulate for all time period (responses that fit may not be one-after-another, but only lay into specified time period). Example: ``total_time(300ms, 70%, 3s)``. Exit code - 25
***total_http** — like ``http``, but accumulated. See ``total_time``. Example: ``total_http(5xx,10%,10s) total_http(3xx,40%,10s)``. Exit code - 26
***total_net** — like ``net``, but accumulated. See ``total_time``. Example: ``total_net(79,10%,10s) total_net(11x,50%,15s)`` Exit code - 27
***negative_http** — inversed ``total_http``. Stop if there are not enough responses that fit the specified mask. Use to be shure that server responds 200. Example: ``negative_http(2xx,10%,10s)``. Exit code: 28
***negative_net** — inversed ``total_net``. Stop if there are not enough responses that fit the specified mask. Example: ``negative_net(0,10%,10s)``. Exit code: 29
***http_trend** - Stop if trend for defined http codes is negative on defined period. Example: http_trend(2xx,10s). Exit code: 30. Trend is a sum of an average coefficient for linear functions calculated for each pair points in last n seconds and standart deviation for it
When test has been finished, module upload to Loadosophia.org test artifacts: file with answer times and files with monitoring data. The link will be shown in console output.
INI file section: **[loadosophia]**
Options
'''''''
***token** - account's access key, received on Upload Token page
***project** - test will be uploaded to that project
***test_title** - test name
***color_flag** - color flag, assigned to test. (gray flag = "to delete")
***file_prefix** - prefix that will be added to uploaded file's name (deprecated
***config** - path to monitoring config file. Default: ``auto`` means collect default metrics from ``default_target`` host. If ``none`` is defined, monitoring won't be executed. Also it is possible to write plain multiline XML config.
***default_target** - an address where from collect "default" metrics. When phantom module is used, address will be obtained from it.
***agent_*.cfg** - configuration files sent to hosts to run monitoring agents.
***agent_<host>_*.log** - monitoring agents' log files, downloaded from hosts
***monitoring_*.data** - data collected by monitoring agents, received by ssh.
***<monitoring config** - monitoring config file
Configuration
'''''''''''''
Net access and authentication
"""""""""""""""""""""""""""""
Monitoring requires ssh access to hosts for copy and executing agents on them. SSH session is established with current user account, so you need to copy your public keys (ssh-copy-id) and enable nonpassword authorization on hosts.
If connection establishing failed for some reason in ``ssh_timeout`` seconds, corresponding message will be written to console and monitoring log and task will proceed further.
Tip: write to ``.ssh/config`` next lines to eliminate ``-A`` option in ``ssh``
::
StrictHostKeyChecking no
ForwardAgent yes
Configuration file format
"""""""""""""""""""""""""
Config is an XML file with structure:
root element ``Monitoring`` includes elements ``Host`` which contains elements-metrics
Contains address and role of monitored server. Attributes:
*``address="<IP address or domain name>"`` - server adddress. Mandatory. Special string ``[target]`` could be used here, which means "get from the tank target address"
Metric elements in general are set by metrics group name and particular metrics enumeration in attribute `measure`. Example: `<CPU measure="idle,user,system" />`
List of metrics group names and particular metrics in them:
* CPU
* idle
* user - default
* system - default
* iowait - default
* nice
* System
* la1 - load average 1 min
* la5 - ...
* la15 - ...
* csw - context switches, default
* int - interrupts, default
* numproc - process amount in system
* numthreads - threads amount in system
* Memory
* free - default
* used - default
* cached
* buff
* Disk
* read - default
* write - default
* Net
* recv - bytes received, default
* send - bytes sent, default
* tx - outgoing packet rate
* rx - incoming packet rate
* retransmit - retransmit amount
* estab - number of sockets in ESTABLISHED state
* closewait - number of sockets in CLOSEWAIT
* timewait - number of sockets in TIMEWAIT
* Custom
* tail - metric value is read from file's last line, file path is specified in node text. Example: `<Custom measure="tail" label="size history">/tmp/dbsize.log</Custom>`
* call - metric value is a command or script execution output. Example: `<Custom measure="call" diff="1" label="Base size">du -hs /usr/mysql/data</Custom>`
Custom metrics have an additional attribute `diff`, that signals to obtain as metric value the difference between previous and current value. So in example above, not the file size, but the dynamic of changes in size will be written.
Also custom metrics must have attribute `label`, which defines metric short name (only latin). `Underline symbol should be avoided.`
Monitoring default logic
****************
Default logic is applied on next levels:
1. Host level: by default target is derived from `address` in `phantom` module.
2. Metrics group level: If config contain host address only, without metrics, i.e `<Host address="somehost.yandex.ru" />`, then default metrics in groups `CPU`, `Memory`, `Disk` are collected. If host has defined any metric, then only it is collected.
3. Metric level: if metrics group is defined without attribute `measure`, then only default group metrics are collected.
There is special non-metric elements called Startup and Shutdown. Startup shell scripts will be started before metric collection. On the normal shutdown startup scripts will be stopped and shutdown scripts will run. There may be any number of Startup and Shutdown elements.
***precise_cumulative** - 0/1, controls the accuracy of cumulative percentile. Default: ``1``. When disabled, cumulative percentiles are calculated with ``time_periods`` precision, otherwise - up to milliseconds.
Module checks free memory and disk space amount before and during test. Test stops if minimum values are reached.
INI file section: **[rcheck]**
Options
'''''''
***interval** - how often to check resources. Default interval: 10s
***disk_limit** - Minimum free disk space in MB. Default: 2GB
***mem_limit** - Minimum free memory amount in MB. Default: 512MB
RC Assert
^^^^^^^^^
Module checks test's exit code with predefined acceptable codes. If exit code matches, it is overrides as 0. Otherwise it is replaced with code from option ``fail_code``
INI file section: **[rcassert]**
Options
'''''''
***pass** - list of acceptable codes, delimiter - whitespace. Default: empty, no check is performed.
***flush_config_to** - dump configuration options after each tank step (`yandex.tank steps. sorry, russian only <http://clubs.ya.ru/yandex-tank/replies.xml?item_no=6>`_) to that file
