Client¶

We provide a simple Python library called swclient that allows you to create users, projects and upload measurements to Snailwatch. You can either use it as a CLI tool or as a library directly in your code.

Installation¶

swclient is located in the client directory. If you just want to use it as a CLI tool, it is enough to install its dependencies from the requirements.txt file:

$ pip install -r requirements.txt

If you want to use it in your code as a library, we recommend to install swclient (preferably in a virtual environment):

$ python setup.py install

CLI usage¶

The following examples assume that swclient is either installed or that you launch the commands from the client subdirectory in the Snailwatch repository.

# create user (email is optional)
$ python -m swclient <server> create-user <admin-token> <username> --email <email>

# create project (repository URL is optional)
$ python -m swclient <server> create-project <session-token> name --repository <repository>

# upload data directly
$ python -m swclient <server> upload <upload-token> my-benchmark '{"commit":"abc"}' '{"result":{"type":"time","value":"15"}}'

# upload data from a JSON file
$ python -m swclient <server> upload-file <upload-token> benchmarks.json

Library usage¶

The designed way to use this library is from a script that is run by a CI service. Your script may look something like this (simplified example that measures a single benchmark once):

import os
import tests

from swclient.client import Client

time_a = tests.benchmark_a()

client = Client(
    '<server>',
    <your-upload-token>
)

client.upload_measurements([(
    'BenchmarkA',       # benchmark name
    {                   # environment of the measurement
        'commit': os.environ['CI_COMMIT'],
        'branch': os.environ['CI_BRANCH'],
        'threads': '16'
    },
    {                   # measured results
        'executionTime': {
            'value': time_a,
            'type': 'time'
        }
    }
)])

Note

When uploading multiple measurements at once, always use the method upload_measurements instead of calling upload_measurement repeatedly. It saves both bandwidth and CPU usage of the server.

CLI documentation¶

usage: python -m swclient [-h]
                          server_url
                          {create-user,create-project,upload,upload-file} ...

Positional Arguments¶

server_url

Address of Snailwatch server

action¶

action

Possible choices: create-user, create-project, upload, upload-file

Sub-commands:¶

create-user¶

Create a user account

python -m swclient create-user [-h] [--email EMAIL] token username

Positional Arguments¶

`token`	Admin token
`username`	Username

Named Arguments¶

--email

E-mail (used for regression notifications)

Default: “”

create-project¶

Create a project

python -m swclient create-project [-h] [--repository REPOSITORY] token name

Positional Arguments¶

`token`	Session token
`name`	Project name

Named Arguments¶

--repository

URL of the project repository

Default: “”

upload¶

Upload a single measurement to Snailwatch

python -m swclient upload [-h] [--timestamp TIMESTAMP]
                          token benchmark env result

Positional Arguments¶

`token`	Upload token
`benchmark`	Benchmark name
`env`	Environment of the benchmark
`result`	Measured result

Named Arguments¶

--timestamp

Time of measurement (YYYY-MM-DDTHH:mm:ss)

upload-file¶

Upload measurement(s) from JSON file

python -m swclient upload-file [-h] token filename

Positional Arguments¶

`token`	Upload token
`filename`	Path to measurement file

API documentation¶

class swclient.client.Client(server_url, token=None)¶

This client provides high-level functions for user and project management and measurement uploads.

Parameters:	server_url – URL of the Snailwatch server token – upload token for uploading measurements, admin token for creating users

create_project(name, repository='')¶

Create a project.

Parameters:	name – Name of the project repository – URL of the project repository

create_user(username, password, email='')¶

Create a user account.

Parameters:	username – Username password – Password (minimum 8 characters) email – E-mail

login(username, password)¶

Log in and return a session token.

Parameters:	username – Username password – Password
Returns:	session token

upload_measurement(benchmark, environment, result, timestamp=None)¶

Uploads a measurement to the server.

Parameters:	benchmark – Benchmark name environment – Environment of the benchmark result – Measured result timestamp – Time of the measurement

upload_measurements(measurements)¶

Uploads multiple measurements at once. Each measurement should be specified as a tuple (benchmark, environment, result, timestamp).

Parameters:	measurements – List of measurements