Acapella CLI

install

Структура

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