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
, которая гарантирует,
что на момент получения ответа на запрос остановки, не будет ни одного активной обработки сервиса
(может приводить к недоступности сервиса на неопределнное время).