Утилиты командной строки

Утилиты командной строки

Яндекс.Танк предоставляет три утилиты: yandex-tank, yandex-tank-ab и yandex-tank-jmeter. Последние два просто используют ab или JMeter вместо phantom в качестве модуля генерации запросов. Опции командной строки у всех одинаковые:

• -h, --help - показать возможные опции командной строки
• -c CONFIG, --config=CONFIG - прочитать из указанного INI-файла опции, можно указать несколько раз. Если эта опция не указана ни разу, то будет сделана попытка прочитать файл load.conf в текущей директории
• -i, --ignore-lock - игнорировать lock-файлы параллельно запущеных утилит
• -f, --fail-lock - вместо ожидания освобождения lock-файла немедленно завершить работу
• -l LOG, --log=LOG - расположение главного log-файла, по умолчанию tank.log в текущей директории
• -m, --manual-start - ожидать нажатия клавиши для запуска теста
• -n, --no-rc - не считывать при запуске конфигурационные файлы /etc/yandex-tank/*.ini и ~/.yandex-tank
• -o OPTION, --option=OPTION - указать конфигурационную опцию из командной строки, она перекроет считанную из конфигурационных файлов. Можно указывать много раз. В начале указывается название секции, затем через точку название опции, после знака равенства - значение. Пример: yandex-tank -o "console.short_only=1" --option="phantom.force_stepping=1"
• -q, --quiet - писать в консоль только сообщения уровня WARNING и ERROR
• -s SCHEDULED_START, --scheduled-start=SCHEDULED_START - запуск теста по расписанию, формат даты YYYY-MM-DD hh:mm:ss, можно указать только время
• -v, --verbose - писать в консоль все возможные сообщения (их будет много, поверьте)

В качестве безымянного параметра командной строки принимается путь к файлу с данными для теста, например yandex-tank ammo.txt

Конфигурирование

Основной способ подачи инструменту информации о необходимых действиях - это INI-файлы. Эти файлы состоят из опций, разбитых на секции. Например:

[phantom]
address=target146.load.net:8080
rps_schedule=const(100,60s)

[autostop]
autostop=instances(80%,10)

Авто-загрузка конфигов

Если не указана опция --no-rc, то Яндекс.Танк при запуске считывает автоматически все конфигурационные файлы *.ini из директории /etc/yandex-tank, а также файл персонального конфига ~/.yandex-tank. Это позволяет делать небольшую персонализацию, помещая в файл ~/.yandex-tank "любимые" настройки, например tank.artifacts_base_dir, phantom.cache_dir, console.info_panel_width

Использование секции DEFAULT

В INI-файлах конфигурации можно использовать магическую секцию DEFAULT, опции из которой действуют во всех прочих секциях. Например, файл вида:

[autostop]
autostop=time(1,10)

[console]
short_only=1

[aggregator]
time_periods=10 20 30 100

[meta]
job_name=ask

можно заменить файлом вида:

[DEFAULT]
autostop=time(1,10)
short_only=1
time_periods=10 20 30 100
job_name=ask

Единственная предосторожность - не использовать в секции DEFAULT опции, которые называются одинаково в разных секциях, например config, иначе получатся непредсказуемые глюки. Однако, чтобы облегчить написание файлов конфигурации, можно в секции DEFAULT использовать опции с указанием секции через точку, например:

[DEFAULT]
monitoring.config=mon.xml
tips.disable=1

Многострочные опции

В INI-формате, при указании опции с одинаковым названием несколько раз, действовать будет лишь значение последней. Однако есть способ указывать многострочные опции, для этого нужно использовать отступы в пару пробелов с новой строки. Например:

[autostop]
autostop=time(1,10)
  http(404,1%,5s)
  net(xx,1,30)

Требуйте поддержки мультистрочных опций в необходимых местах от разработчиков Яндекс.Танка!

Shell-опции

Если указать значение опции внутри обратных кавычек, то будет сделан shell-вызов и вывод stdout будет присвоен опции (так же, как делает это bash). Например:

[meta]
job_name=`pwd`

Ссылка одной опции на другую

Синтаксис %(optname)s позволяет ссылаться на значение другой опции внутри одной секции. Вкупе с секцией DEFAULT это позволяет избегать дублирования, например, так:

[DEFAULT]
host=target12.load.net

[phantom]
address=%(host)s:8080

[monitoring]
default_target=%(host)s

[shellexec]
prepare=echo Target is %(host)s

Единицы измерения

Во всех опциях, где это имеет смысл, можно применять сокращенное написание единиц в миллисекундах или секундах. Например, в автостопе вместо time(30000,120) можно написать time(30s,2m). При этом можно смешивать единицы измерения, например 1h30m15s или 2s15ms. Если в каком-то месте инструмента такая функция отсутствует - это баг.

Артефакты

В результате работы инструмента получается некоторое количество файлов с логами, результатами и конфигами. Эти файлы в конце теста аккуратно складываются в одну директорию, называемую директорией артефактов. Место расположения этой директории определяется опцией artifacts_base_dir в секции tank. Рекомендуется настроить эту опцию таким образом, чтобы артефакты теста, запущенного из любой директории, попадали в одно место, например ~/yandex-tank-artifacts, это облегчит периодическую чистку свободного места.

Модули

В описаниях модулей ниже красная звездочка !!*****!! означает обязательную опцию.

Phantom

Модуль генератора нагрузки с использованием утилиты phantom. Секция INI-файла: [phantom] Основные опции:

• ammofile - путь к файлу с исходными запросами
• rps_schedule - расписание подачи нагрузки в виде RPS
• instances - максимальное число тестирующих потоков
• instances_schedule - расписание подачи нагрузки в виде тестирующих потоков
• loop - ограничение повторов исходного множества запросов
• autocases - рассчитывать ли в исходном файле маркеры запросов автоматически Дополнительные опции:
• writelog - писать ли детальный лог запросов/ответов. Возможные значения: 0 - не писать, all - писать все, proto_warning - писать 4хх+5хх+сетевые ошибки, proto_error - писать 5хх+сетевые ошибки. По умолчанию: 0
• ssl - включить SSL, 1 - включить, 0 - не включать, по умолчанию: 0
• address - адрес тестируемого сервиса. Для доменных имен и адресов IPv4 может содержать порт, отделенный двоеточием. Для доменного имени делается резолв IP-адреса, а затем обратный резолв IP-адреса в имя, для проверки корректности имени. По умолчанию: 127.0.0.1
• port - порт тестируемого сервиса, по умолчанию: 80
• gatling_ip - использовать указанные локальные IP-адреса, а не только один (помогает при достижении лимита открытых портов). Список, разделенный пробелами
• tank_type - тип используемого протокола. Возможные значения: http, none ("сырой" TCP). Если указано пустое значение, то элементы proto в конфиге phantom будут отсутствовать. По умолчанию: http
• eta_file - файл, в который будет сбрасываться информация об оставшемся времени теста Опции URI-формата запросов:
• uris - список тестируемых URI, многострочный параметр
• headers - список заголовков для добавления в каждый запрос, в формате [Заголовок: значение], многострочный параметр
• header_http - версия HTTP для указания в запросах, по умолчанию: 1.0 Опции кэша stpd-файлов:
• use_caching - флаг включения кэша, по умолчанию: 1
• cache_dir - директория для хранения файлов кэша, по умолчанию - базовая директория хранения артефактов
• force_stepping - флаг принудительного степпинга, по умолчанию: 0 Продвинутые опции:
• phantom_path - путь к утилите phantom, по умолчанию: phantom
• phantom_modules_path - путь к модулям phantom, по умолчанию:/usr/lib/phantom
• config - не генерировать конфиг для phantom, а использовать указанный
• phout_file - вместо запуска phantom импортировать файл результатов phout
• stpd_file - вместо генерации stpd-файла использовать указанный
• threads - число тредов, выделяемых для обслуживания phantom, по умолчанию - 1+половина числа ядер системы
• buffered_seconds - число секунд, на которое будет отставать агрегатор результатов, чтобы быть уверенным в том, что прочел точно все данные phout
• additional_libs - список, разделенный пробелами, будет добавлен в секцию module_setup конфига phantom
• method_prefix - тип объекта, несущего функциональность создания тестовых запросов. По умолчанию: method_stream
• source_log_prefix - префикс, добавляемый к названию класса-читалки исходных данных. По умолчанию: пусто Опции тюнинга http-модуля phantom:
• phantom_http_line
• phantom_http_field_num
• phantom_http_field
• phantom_http_entity Артефакты:
• phantom*.conf_ - сгенерированный файл конфигурации
• phout*.log_ - файл сырых результатов
• phantom_stat*.log_ - файл посекундной информации о работе phantom
• answ*.log_ - файл детальных запросов/ответов
• phantom*.log_ - внутренний лог работы phantom

Мульти-стрельбы

Чтобы сделать несколько стрельб фантомом, достаточно добавить произвольное количество секций c именами phantom-N, и использовать в них те же опции что и у основной секции. Результаты всех секций будут читаться одновременно. Мульти-стрельба закончится как только закончится первая из составляющих ее стрельб. Например:

[phantom]
phantom_path=phantom
ammofile=data/dummy.ammo
instances_schedule=line(1,10,1m)
loop=1
use_caching=1

[phantom-1]
uris=/
        /test
        /test2
headers=[Host: www.ya.ru]
        [Connection: close]
rps_schedule=const(1,30) line(1,1000,2m) const(1000,5m)
address=fe80::200:f8ff:fe21:67cf
port=8080
ssl=1
instances=3
gatling_ip=127.0.0.1 127.0.0.2
phantom_http_line=123M

[phantom-2]
uris=/3
rps_schedule=const(1,30) line(1,50,2m) const(50,5m)

Опции, которые действуют только для основной секции: buffered_seconds, writelog, phantom_modules_path, phout_file, config, eta_file, phantom_path

Мониторинг

Запускает ((/nagruzochnoetestirovanie/lunapark/dev/monitoring/configuring сбор мониторинга через ssh-подключение)). Секция INI-файла: [monitoring] Опции:

• config - путь к файлу с настройкой сбора мониторинга, по умолчанию: auto, это означает что будет сделана попытка собрать мониторинг "по умолчанию" с мишени default_target. Если установить значение в none, то мониторинг собираться не будет. Также можно написать в параметр прямо содержимое XML-конфига, включая многострочный.
• default_target - адрес хоста, с которого собирать мониторинг "по умолчанию". При наличии модуля phantom делается попытка получить от него адрес тестируемого хоста
• ssh_timeout - таймаут соединения с ssh, по умолчанию: 5s Артефакты:
• agent*.cfg_ - файлы конфигурации, которые отправлялись на хосты для запуска агента мониторинга
• agent<хост>*.log - файлы логов агента мониторинга, скачанные по возможности с хостов
• monitoring*.data_ - данные агентов мониторинга, прочитанные по ssh
• <конфиг мониторинга> - копия конфигурационного файла мониторинга

Авто-стоп

Модуль получает данные от агрегатора и передает их объектам-критериям автостопа. При обнаружении объектом-критерием необходимости остановить тест, он делает это. Секция INI-файла: [autostop] Опции:

• autostop - список критериев автостопа, разделенных пробелами. Формат критериев таков: тип(параметры) Доступные типы критериев:
• time - остановить тест, если среднее время ответа превышает заданный порог в течение заданного времени, код выхода 21. Например: time(1s500ms, 30s) time(50,15)
• http - остановить тест, если число кодов HTTP, соответствующих маске, более заданного абсолютного или относительного порога, код выхода 22. Примеры: http(404,10,15) http(5xx, 10%, 1m)
• net - аналогично HTTP-кодам, но для сетевых кодов ответа, код выхода 23. допустима маска xx, означающая "все ненулевые"
• quantile - остановить тест, если выбранный процентиль выше определенного уровня таймингов в течение N секунд. Список допустимых квантилей: 25, 50, 75, 80, 90, 95, 98, 99, 100. Например: quantile (95,100ms,10s)
• instances - тип добавляется при подключении модуля Phantom. Тест останавливается, если число активных инстансов выше абсолютного или относительного порога, код выхода 24. Например: instances(80%, 30) instances(50,1m)
• total_time — остановить тест, если N% ответов превышает порог времени ответа в течение заданного интервала времени. От time отличается тем, что аккумулирует информацию, это означает что в заданном интервале могут быть секунды, которые не удовлетворяют критерию, но весь интервал в целом удовлетворяет заданным условиям, код выхода 25. Например: total_time(100ms,70%,3s)
• total_http — остановить тест, если N% (или абсолютное значение) ответов пришли с кодом по заданной маске в течение заданного времени. Так же, использует аккумуляцию, код выхода 26. total_http(5xx,10%,10s) total_http(3xx,40%,10s)
• total_net — остановить тест, если N% (или абсолютное значение) ответов пришли с кодом по заданной маске в течение заданного времени. Аккумулирующий критерий, код выхода 27. Примеры: total_net(79,10%,10s) total_net(11x,50%,15s)
• negative_http — остановить тест если более N% кодов ответов не подходят под заданную маску. Например, если у нас упал backend и front начал кидать 3xx вместо 2xx, можно написать следующий критерий, код выхода 28: negative_http(2xx,10%,10s). В этом примере стрельба остановится, если количество _НЕ_200ок превысит 10%.
• negative_net — остановить тест если более N% кодов ответов не подходят под заданную маску. Например, если обстреливаемое приложение стало некорретно отвечать на уровне TCP (т.е. стали лететь ошибки Protocol Error 71, а иногда ловим 104/110), то можно написать следующий критерий, код выхода 29: negative_net(0,10%,10s). В этом примере стрельба остановится, если доля всех сетевых ошибок превысит 10% за последние 10 секунд.
• http_trend — автостоп, который следит за трендом ответов с заданной маской. Например, сервис корретно отвечает на 300rps, но дальше при повышении нагрузки до 350rps количество ответов начало снижаться. Тогда можем написать критерий http_trend(2xx,10s). Если тренд двухсоток за последние 10 секунд начал снижаться с учетом погрешности измерения, то останавливать тест. Необходим чтобы для каждого сервиса и его конфигурации не подбирать границы времен ответа для определния момента разладки. Код выхода 30.
• metric_lower и metric_higher - срабатывают если значение метрики мониторинга ниже/выше порога в течение заданного времени, коды выхода 31 и 32. Пример: metric_lower(127.0.0.1,Memory_free,500,10). Обратите внимание, что имена метрик (кроме кастомных) пишутся не через пробел, а через подчеркивание. В именах хостов можно использовать маски а-ля имена файлов (Пример: target-*.yandex.ru).

Консольный экран

Отображает информацию о ходе теста в текстовой консоли Секция INI-файла: [console] Опции:

• short_only - отображать сокращенную информацию по одной строке в секунду вместо полноэкранной, 1 - сокращенная, 0 - полноэкранная, по умолчанию 0
• info_panel_width - относительная ширина правой панели в процентах, по умолчанию 33
• disable_all_colors - отключить цветную раскраску, 0/1, по умолчанию 0
• disable_colors - список цветов из раскраски, которые будут отключены, список, разделенный пробелами. Пример: WHITE GREEN RED CYAN MAGENTA YELLOW

Агрегатор

Модуль отвечает за агрегацию получаемых от модулей генерации нагрузки данных и передачу агрегированных данных объектам-потребителям. Например, модуль консольного экрана - яркий представитель потребителей агрегированных данных. Секция INI-файла: [aggregator] Опции:

• time_periods - интервалы в миллисекундах, по которым будет вестись округление результатов, разделители списка - пробелы. По умолчанию: 1ms 2 3 4 5 6 7 8 9 10 20 30 40 50 60 70 80 90 100 150 200 250 300 350 400 450 500 600 650 700 750 800 850 900 950 1s 1500 2s 2500 3s 3500 4s 4500 5s 5500 6s 6500 7s 7500 8s 8500 9s 9500 10s 11s

ShellExec

Модуль выполняет shell-скрипты (т.н. хуки) на разных этапах работы, это позволяет запускать/останавливать сервис непосредственно перед тестом. Каждый хук считается успешным если имеет код выхода 0, в противном случае тест будет остановлен. Вывод stdout хука будет записан в DEBUG-лог, вывод stderr будет распечатан как сообщения WARNING. Секция INI-файла: [shellexec] Опции:

• prepare - выполняется при подготовке теста
• start - выполняется на этапе старта теста
• poll - выполняется при ежесекундном опросе модулей на предмет завершенности теста
• end - выполняется при остановке теста
• postprocess - выполняется на этапе пост-обработки результатов

JMeter

Модуль использования генератора нагрузки JMeter. Секция INI-файла: [jmeter] Опции:

• !!*****!!jmx - файл тест-плана для запуска
• args - дополнительные аргументы командной строки запуска JMeter
• jmeter_path - путь к JMeter, позволяет запустить альтернативную инсталляцию, по умолчанию: jmeter Артефакты:
• <оригинальный jmx> - исходный файл тест-плана
• modified*.jmx_ - модифицированный тест-план, после добавления в него блока записи результатов
• jmeter*.jtl_ - файл результатов JMeter
• jmeter*.log_ - файл лога JMeter

AB

Модуль использования генератора нагрузки Apache Benchmark. Утилита ab имеет специфику того, что результаты в файл сбрасывает только в самом конце теста. Из-за этого в Яндекс.Танке приходится весь тест ждать "вслепую" и лишь по завершении теста все данные будут обработаны разом. Секция INI-файла: [ab] Опции:

• url - запрашиваемый URL, по умолчанию: http:_localhost/
• requests - общее число запросов, которые необходимо выполнить, по умолчанию: 100
• concurrency - число параллельных потоков, которые будут задействованы, по умолчанию: 1
• options - дополнительные опции командной строки для утилиты ab Артефакты:
• ab*.log_ - лог запросов с таймингами

Tips&Tricks

Модуль отображает небольшие советы по использованию инструмента в полноэкранной консоли. Если у вас есть дельные советы и хитрости, которые можно добавить в tips&tricks - сообщайте разработчикам Секция INI-файла: [tips] Опции:

• disable - отключить отображение советов, 1 - отключить, 0 - не отключать, по умолчанию 0

Web Online

Модуль запускает локальный веб-сервер, умеющий показывать графики онлайн-теста. Секция INI-файла: [web] Опции:

• port - локальный порт, на котором будет запущен сервер. По умолчанию: 8080
• interval - интервал в секундах, который будет отображаться на графике. По умолчанию: 1 минута
• redirect - адрес, на который перенаправлять браузер после завершения теста
• manual_stop - флаг 0/1, при установке в 1 перед остановкой веб-сервера будет запрошено нажатие клавиши в консоли

Resource Check

Модуль проверяет перед тестом и в процессе теста, не кончаются ли память и дисковое пространство. Если кончаются - тест прерывается. Секция INI-файла: [rcheck] Опции:

• interval - периодичность, с которой будут проверяться ресурсы в процессе теста. По умолчанию: 10 секунд
• disk_limit - размер в МБ минимального свободного места на диске, по умолчанию: 2ГБ
• mem_limit - размер в МБ минимальной свободной памяти, по умолчанию: 512МБ (в Яндексе 1ГБ)