clmc-service.md

Flame CLMC Service Documentation

Authors

Authors	Organisation
Nikolay Stanchev	University of Southampton, IT Innovation Centre

Description

This document describes the CLMC service and its API endpoints. The CLMC service is implemented in the Python framework called Pyramid. It offers different API endpoints to configure and control the aggregator, which is an essential part in the process of measuring the end-to-end performance. All source code, tests and configuration files of the service can be found in the src/clmc-webservice folder.

API Endpoints

• GET /aggregator/config

  This API method retrieves information about the configuration of the aggregator.

  • Response:

    Returns a JSON-formatted response with the configuration data of the aggregator - aggregator_report_period, aggregator_database_name, aggregator_database_url.

  • Response Body Example:

    {
      "aggregator_report_period": 5,
      "aggregator_database_name": "E2EMetrics",
      "aggregator_database_url": "http://172.40.231.51:8086"
    }

• PUT /aggregator/config

  This API method updates the configuration of the aggregator.

  • Request:

    Expects a JSON-formatted request body with the new configuration of the aggregator. The body should contain only three key fields - aggregator_report_period (positive integer, seconds), aggregator_database_name and aggregator_database_url (a valid URL).

  • Request Body Example:

    {
      "aggregator_report_period": 25,
      "aggregator_database_name": "E2EMetrics",
      "aggregator_database_url": "http://172.50.231.61:8086"
    }

  • Response:

    The body of the request is first validated before updating the configuration. If validation is successful, returns a JSON-formatted response with the new configuration data. Otherwise, an HTTP Bad Request response is returned.

  • Response Body Example:

    {
      "aggregator_report_period": 25,
      "aggregator_database_name": "E2EMetrics",
      "aggregator_database_url": "http://172.50.231.61:8086"
    }

  • Notes:

    If the configuration is updated, while the aggregator is running, it is not automatically restarted. An explicit API call must be made with a restart request to apply the updated configuration. In the case of such PUT request as the one described above, the response will contain more information indicating that the configuration of the aggregator is in a malformed state.

    • Response Body Example:

      {
        "aggregator_report_period": 125,
        "aggregator_database_name": "E2EMetrics",
        "aggregator_database_url": "http://172.50.231.61:8086/",
        "malformed": true,
        "comment": "Aggregator is running in a malformed state - it uses an old version of the configuration. Please, restart it so that the updated configuration is used."
      }

• GET /aggregator/control

  This API method retrieves information about the status of the aggregator - whether it is running or not.

  • Response:

    Returns a JSON-formatted response with the status data of the aggregator - aggregator_running field. If the aggregator is running in a malformed state, the response will also indicate this with two additional fields - malformed and comment.

  • Response Body Example:

    {
      "aggregator_running": true
    }

  • Response Body Example - for malformed configuration:

    {
      "aggregator_running": true,
      "malformed": true,
      "comment": "Aggregator is running in a malformed state - it uses an old version of the configuration. Please, restart it so that the updated configuration is used."
    }

• PUT /aggregator/control

  This API method updates the status of the aggregator - a user can start, stop or restart it.

  • Request:

    Expects a JSON-formatted request body with the new status of the aggregator. The body should contain only one key field - action (the action to undertake, which can be start, restart or stop)

  • Request Body Example:

    {
      "action": "start"
    }

  • Response:

    The body of the request is first validated before taking any actions. If the action is not one of the listed above, then the validation will fail. If validation is successful, returns a JSON-formatted response with the new status of the aggregator. Otherwise, an HTTP Bad Request response is returned.

  • Response Body Example:

    {
      "aggregator_running": true
    }

  • Notes:

    • If a start action is requested, while the aggregator is running, then the request will be ignored. To restart the aggregator, a user should use a restart action.

    • If a stop action is requested, while the aggregator is not running, then the request will be ignored.

    • A request with a restart action, while the aggregator is not running, has the same functionality as a request with a start action.

    • The functionality of a request with a restart action is the same as the functionlity of a stop action followed by a start action.

Installing and running the CLMC service (development mode)

Before installing the CLMC service and its dependencies, it is recommended to use a python virtual environment. To easily manage virtual environments, virtualenvwrapper can be used.

pip install virtualenvwrapper

To create a virtual environment use the mkvirtualenv command:

mkvirtualenv CLMC

When created, you should already be set to use the new virtual environment, but to make sure of this use the workon command:

workon CLMC

Now, any installed libraries will be installed relative to this environment only.

The easiest way to install and use the CLMC service locally is to use pip. Navigate to the clmc-webservice folder:

cd src/clmc-webservice

Test the CLMC service using tox along with the tox.ini configuration file. If tox is not installed run:

pip install tox

After it is installed, simply use the tox command:

tox

Then install the service in development mode.

pip install -e .

Finally, start the service on localhost by using pyramid's pserve:

pserve development.ini --reload

You should now be able to make requests to the CLMC service on http://localhost:9080/aggregator/config and http://localhost:9080/aggregator/control.