Acapella CLI¶
install¶
- you need
python 3.6. how to install python3.6 page. - get cli from github https://github.com/AcapellaSoft/acapella_cli
Структура¶
Файлы CLI утилиты:
- cli |- [acapella_api] |- [py_launcher] |- acapella <-- Исполняемый скрипт запуска
Общая структура команд как у git:
acapella --help
->
usage: acapella <command> [<args>] Available commands: upload upload fragments to acapella fragment store start start transaction run upload directory and start transaction register sign up for Acapella login login and store session data in ``/.netrc` logout log out and remove session data from ``/.netrc` presets dump deafult presets snapshots snapshot management transactions list, stop, remove transactions fragments list fragments in specified snapshot version print CPVM and CLI launcher versions Acapella CLI 0.7 positional arguments: command subcommand to run: login, logout, presets, run, snapshots, start, upload, version optional arguments: -h, --help show this help message and exit
Справка по отдельным коммандам:
acapella run --help
->
usage: acapella run [-h] [--trid TRID] [--args DICT_OF_ARGS] [--kvio] [--logs LOGS] [--preset PRESET] [--path PATH] fname upload directory and start transaction positional arguments: fname fragment file path relative to current snapshot path (by default its current path). Example: path/to/fragment.lua optional arguments: -h, --help show this help message and exit --trid TRID custom transaction ID --args DICT_OF_ARGS map of root fragment arguments: {"p1":"v1", "p2":"v2"} --kvio allow TVM KV IO --logs LOGS logging mode: realtime, offline, none --preset PRESET 'transactional', 'acapella', 'single'. You can add your custom preset: just put '*.json' file of preset to the launcher folder --path PATH specify root directory of the snapshot
--kvio эквивалентен "beginKvTransaction": false, -> "beginKvTransaction": true , в transaction parameters
Авторизация¶
Если runtime развернут в тестовом режиме можно использовать логин и пароль "тестового" пользователя ($TEST_USER/qwerty123),
в противном случае, перед началом работы с CLI-утилитой необходимо завести аккаунт.
acapella register
->
Username: Alex Password: Retry password: E-mail: wdoker@gmail.com Retry E-mail: wdoker@gmail.com Thank you for registering Check out wdoker@gmail.com Be sure to check your spam folder before next registration attempt
После верификации аккаунта можно запросить токен:
acapella login
->
Username: Alex Password: session data saved in ~/.netrc logged in as Alex
Утилита сохраняет токен в файл ~/.netrc (поле password).
Длительность сессии можно указать через параметр --expire <Xsec>/<Xm>/<Xh>/<Xd>.
Отключить сохранение сессии можно через параметр --nonetrc (логин и пароль будут запрашиваться для любой команды).
* Деактивировать все прошлые сессии можно параметром--clear.
Удаление сессий:
acapella logout
Запуск транзакций¶
Имеем следующие фрагменты: (примеры фрагментов , fragment api)
- root.lua - f3.py - lib1 |- f1.lua |- f2.py - lib2 |- f1.lua |- f2.py
Переходим в папку с фрагментами и запускаем root.lua:
acapella run root.lua
->
snapshot created: $TEST_USER/cli-launcher/7C7D0463
6 fragments not found in fragment store
uploading fragments:
f3.py
root.lua
lib1/f1.lua
lib1/f2.py
lib2/f1.lua
lib2/f2.py
snapshot is ready
CPVM 1.2.744 (ea670221a04d3d26b18b17770b06e55e83290282)
using 'transactional' preset
start fragment: $TEST_USER/cli-launcher/7C7D0463:mult_root.lua
transaction started: f39726e195844944
transaction completed
execution time:
without overheads (worker): 1 ms
total (worker): 1 ms
total (node): 2 ms
transaction timestamps:
start: 15:51:25.579000 [2017-11-12]
rnd: 15:51:25.581000 [2017-11-12]
counters:
total conflicts: 0
total restarts: 0
async calls: 4
sync calls: 0
TVM reads: 210
TVM writes: 30
TVM traffic:
TVM bytes read: 650 B
TVM bytes write: 570 B
Команда run - это особая комбинация команд upload и start.
Она создает снапшот и загружает в него все .py и .lua фрагменты в текущей папке.
Текщуая папка становится "корнем" снапшота. При этом, если хеши фалов совпадают с хешами фалов какого-то существующего снапшота,
к которому у текщего пользователя есть доступ, то этот снапшот переиспользуется полностью.
При частичном совпадении создается новый снапшот, но совпадающие фрагменты добавляются в него автоматически и не требуют повторной загрузки:
acapella run root2.lua
->
snapshot created: $TEST_USER/cli-launcher/D9CD5C28 1 fragment not found in CodeBase upload fragment: root2.py snapshot is ready CPVM 1.2.744 (ea670221a04d3d26b18b17770b06e55e83290282) using 'transactional' preset start fragment: $TEST_USER/cli-launcher/D9CD5C28:mult_root.py transaction started: 24199de60d348c0
acapella run root2.lua
->
matches with existing snapshot: $TEST_USER/cli-launcher/D9CD5C28 CPVM 1.2.744 (ea670221a04d3d26b18b17770b06e55e83290282) using 'transactional' preset start fragment: $TEST_USER/cli-launcher/D9CD5C28:mult_root.py transaction started: 18d9242e86c54d30
Конфигурация запуска¶
Задется пресетами, каждый из которых может быть представлен json-файлом.
Вывести стандартные пресеты можно командой presets (выводит все пресеты в виде json).
Указав параметр --name можно вывести один пресет:
acapella presets --name transactional
->
{ "allowConvertAsyncToSync": false, "allowConvertSyncToAsync": false, "allowRestart": true, "allowSubFragments": true, "arguments": {}, "beginKvTransaction": false, "failover": false, "fragment": "TEST_USER/Unnamed/default:main.lua", "logging": { "allowCreateLogs": false, "redirections": { "stderr": { "id": "log", "ordering": "PARTIAL", "scope": "TRANSACTION" }, "stdout": { "id": "log", "ordering": "PARTIAL", "scope": "TRANSACTION" } } }, "resolveConflicts": false, "syncTvmIo": true, "tvmCount": 3 }
Пресет можно сохранить в файл рядом с исполняемым файлом CLI-утилиты и кастомизировать. Название файла будет соответствовать названию пресета:
acapella presets --name transactional > my_preset.json nano my_preset.json ... acapella run root.lua --preset my_preset
Некоторые параметры запуска можно переопределять на ходу:
acapella run --trid "12345" --args '{"p1":"v1", "p2":"v2"}' --kvio --logs offline
Полный список аргументов команды run:
acapella run --help
->
usage: acapella run [-h] [--trid TRID] [--args DICT_OF_ARGS] [--kvio] [--logs LOGS] [--preset PRESET] [--path PATH] fname upload directory and start transaction positional arguments: fname fragment file path relative to current snapshot path (by default its current path). Example: path/to/fragment.lua optional arguments: -h, --help show this help message and exit --trid TRID custom transaction ID --args DICT_OF_ARGS map of root fragment arguments: {"p1":"v1", "p2":"v2"} --kvio allow TVM KV IO --logs LOGS logging mode: realtime, offline, none --preset PRESET 'transactional', 'acapella', 'single'. You can add your custom preset: just put '*.json' file of preset to the launcher folder --path PATH specify root directory of the snapshot
Запуск фрагмента в существующем снапшоте¶
acapella start 'TEST_USER/cli-launcher/7C7D0463:lib1/fr1.lua'
Остановка транзакции¶
acapella stop "93804079ff3f437f"
Если необходимо дождаться момента, когда все фрагменты транзакции будут остановлены, то необходимо передать параметр --sync
Залив фрагментов в новый или существующий снапшот¶
acapella upload --sn_name 'MyProject' f1.lua f2.py
Добавляем фрагменты в существующий снапшот:
acapella upload --sn_id 'TEST_USER/MyProject/v1.2' f1.lua f2.py
Вывод списка снапшотов¶
acapella snapshots
->
$TEST_USER/cli-launcher/7C7D0463
frozen: True
created: 15:37:59.591000 [2017-11-12]
expireAt: 15:37:59.591000 [2017-11-26]
accessLevel: Invisible
$TEST_USER/cli-launcher/A81CC544
frozen: True
created: 15:39:41.502000 [2017-11-12]
expireAt: 15:39:41.502000 [2017-11-26]
accessLevel: Invisible
Вывод списка транзакций¶
acapella transactions
->
5695568798dd4bad
state: finished
84daeac8c0f54373
state: running
8e04cd5a02e74ba1
state: finished
93804079ff3f437f
state: running
a0c6a9a176b94a39
state: running
Вывод логов¶
Следующая комманда выводит общий лог log транзакции 93804079ff3f437f пользователя user:
acapella log '@user/93804079ff3f437f/log'
Вывод лога log исполнения 1.0.255 фрагмента fragment.py транзакции 5695568798dd4bad текущего пользователя:
acapella log '5695568798dd4bad/fragment.py/1.0.255/log'
Вывод общего лога fr_log фрагмента fragment.py транзакции 84daeac8c0f54373 текущего пользователя:
acapella log '84daeac8c0f54373/fragment.py/fr_log'
Вывод общего лога all-events текущего пользователя:
acapella log 'all-events'
Команду можно запускать до, после и во время исполнения транзакции/фрагмента.
Если команда вызвана до создания указанного лога, cli будет ждать его появления 3 сек (пока этот таймаут нельзя изменить).
Лог создается лениво при первой записи в него, так что, если ваш фрагмент работает долго и тихо, а самом конце печатает hello world,
то подловить момент когда нужно читать лог будет сложно.
Вывод списка сервисов¶
acapella services
$TEST_USER/cli-launcher/7C7D0463:my_service.yml
running: False
$TEST_USER/cli-launcher/7C7D0463:another/service/in/the/same/snapshot/swagger.yml
running: False
$TEST_USER/cli-launcher/7C7D0463:petstore.yml
running: True
Запуск и остановка сервиса¶
Запуск и остановку сервиса можно производить также, как и для фрагментов:
acapella run my_service.yml
или
acapella start 'cli-launcher/7C7D0463:my_service.yml'
Остановка:
acapella stop 'cli-launcher/7C7D0463:my_service.yml'
Установка стратегии обновления сервиса пока недоступна. По умолчанию используется стратегия STOP_SYNC, которая гарантирует,
что на момент получения ответа на запрос остановки, не будет ни одного активной обработки сервиса
(может приводить к недоступности сервиса на неопределнное время).