CPVM HTTP API: Transactions

Start transaction

Asynchronous transaction start. To check the status of a transaction, you need to call the /vm/transactions/{trId}/awaitState or /vm/transactions/{trId}/await.

curl -XPOST --netrc \
-H "Content-Type: application/json" \
-d "@tr_parameters.json" \
https://api.acapella.ru/vm/start 

tr_parameters.json:

{
    "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,
    "tvmCount": 3
}

Full description of each parameter can be found here.

Response:

{
  "transactionId": "0AEC28B47DE6AC8098C18D10390DB1D"
}

Stop transaction

curl -XPOST --netrc https://api.acapella.ru/vm/stop?trId=0AEC28B47DE6AC8098C18D10390DB1D&sync=false

Arguments: - trId: transaction ID. It can be specified by the user or generated automaticly in /vm/start - sync: if true runtime will wait for all fragments to be terminated before responding to this request

List transactions

Get list of all transactions:

curl -XGET --netrc https://api.acapella.ru/vm/transactions/0AEC28B47DE6AC8098C18D10390DB1D

Response:

[
    {
      "id": "0AEC28B47DE6AC8098C18D10390DB1D", 
      "params": {
          "allowRestart": true,
          "allowSubFragments": true
          // ... 
          // other transaction parameters              
      }, 
      "status": {
          "state": "finished", 
          "result": "",
          "errorCode": null
      }
    }
]

Possible transaction states: queued - The transaction has not started yet initialization - Preparing for execution of the transaction (for example, loading docker images, launching workers) running - Transaction is running suspended - Transaction paused ok - Transaction completed successfully error - The transaction was stopped due to an error in one of the fragment. In the result there will be the error message, and the error code inerrorCode.

Check specific transaction:

curl -XGET --netrc https://api.acapella.ru/vm/transactions/0AEC28B47DE6AC8098C18D10390DB1D

Wait transaction

Long-poll request for waiting for the one of the specified transaction states.

curl -XGET --netrc -d 'states=["error", "finished"]' https://api.acapella.ru/vm/transactions/0AEC28B47DE6AC8098C18D10390DB1D/awaitState

Long-poll request for waiting for transaction completion (success or error):

curl -XGET --netrc https://api.acapella.ru/vm/transactions/0AEC28B47DE6AC8098C18D10390DB1D/await

Get transaction counters

Can be called while transaction is runnning.

curl -XGET --netrc https://api.acapella.ru/vm/transactions/0AEC28B47DE6AC8098C18D10390DB1D/counters

Response:

{
    "totalRestarts": 0,
    "totalConflicts": 0,

    // UTC, milliseconds
    "startTimestamp": 1516190836329,
    "ioStartTimestamp": 1516190836510,
    "endTimestamp": 1516190837003,

    // milliseconds
    "workerExecTime": 120,
    "workerExecTimeTotal": 141,
    "nodeExecTime": 284
}

Timings: workerExecTime - pure caclulation time without overheads (measured by worker) workerExecTimeTotal - total execution time measured by worker * nodeExecTime - total transaction time

Remove transaction

curl -XGET --netrc https://api.acapella.ru/vm/transactions/0AEC28B47DE6AC8098C18D10390DB1D/counters

If the transaction is currently running, it will be scheduled for deletion immediately after the transaction is completed.

Logs belonging to this transaction will also be deleted (scopes TRANSACTION, FRAGMENT, EXECUTION).