Skip to content
Snippets Groups Projects
Commit 4e5649e9 authored by Stephen Phillips's avatar Stephen Phillips
Browse files

Formatting fixes

parent 52c998da
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 124 additions and 123 deletions
docs/clmc-service.md
+ 124
− 123
View file @ 4e5649e9
......@@ -2,7 +2,7 @@
// © University of Southampton IT Innovation Centre, 2018
//
// Copyright in this software belongs to University of Southampton
// IT Innovation Centre of Gamma House, Enterprise Road,
// IT Innovation Centre of Gamma House, Enterprise Road,
// Chilworth Science Park, Southampton, SO16 7NS, UK.
//
// This software may not be used, sold, licensed, transferred, copied
......@@ -25,8 +25,8 @@
#### **Authors**
|Authors|Organisation|
|---|---|
|Authors|Organisation|
|---|---|
|[Nikolay Stanchev](mailto:ns17@it-innovation.soton.ac.uk)|[University of Southampton, IT Innovation Centre](http://www.it-innovation.soton.ac.uk)|
#### Description
......@@ -35,7 +35,7 @@ This document describes the CLMC service and its API endpoints. The CLMC service
It offers different API endpoints to configure and control the aggregator as well as a CRUD API for service function endpoints configuration data and Graph API for calculating round trip time. All source code, tests and configuration files of the service can be found in the **src/service** folder.
#### Graph API Endpoints
## Graph API Endpoints
* **Assumptions**
* For each service function, there is a field/fields from which the service function response time (service delay) can be derived.
......@@ -49,13 +49,13 @@ It offers different API endpoints to configure and control the aggregator as wel
This API method sends a request to the CLMC service to build a graph related to the time range declared with the *from* and *to* URL parameters.
* Request:
Expects a JSON-formatted request body which declares the database, retention policy and service function chain instance for which the graph is built.
The request should also include the service functions that must be included in the graph along with the measurement name, response time field, request size field and
response size field for each service function. The declared fields could be influx functions across multiple fields.
* Request Body Example:
* Request Body Example:
```json
{
"database": "MSDemo",
......@@ -77,34 +77,34 @@ It offers different API endpoints to configure and control the aggregator as wel
}
}
```
These parameters are then filled in the following influx query template:
```
SELECT {0} AS mean_response_time, {1} AS mean_request_size, {2} AS mean_response_size FROM "{3}"."{4}".{5} WHERE sfc_i='{6}' and time>={7} and time<{8} GROUP BY ipendpoint, location, sf_i
```
E.g. for the minio service function, the following query will be used to retrieve the data from influx (request url is /graph/build?from=1528385420&to=1528385860):
```
SELECT mean(sum)/mean(count) AS mean_response_time, mean(request_size)/mean(count) AS mean_request_size, mean(response_size)/mean(count) AS mean_response_size FROM "MSDemo"."autogen".minio_http_requests_duration_seconds WHERE sfc_i='MSDemo_1' and time>=1528385420000000000 and time<1528385860000000000 GROUP BY ipendpoint, location, sf_i
```
N.B. timestamps are converted to nano seconds.
* Response:
The response of this request is a JSON content, which contains all request parameters used to build the graph, along with a request UUID. This request ID can then be used to manage the temporal subgraph that was created
in response to this request.
Returns a 400 Bad Request error if the request body is invalid.
Returns a 400 Bad Request error if the request URL parameters are invalid or missing.
Returns a 400 Bad Request error if the service function chain instance ID is not in the format `<sfcID>_<numberID>`
* Response Body Example:
* Response Body Example:
```json
{
"database": "MSDemo",
......@@ -132,27 +132,27 @@ It offers different API endpoints to configure and control the aggregator as wel
}
}
}
```
```
* **DELETE** ***/graph/temporal/{graph_id}***
This API method sends a request to delete the temporal graph associated with a given request UUID (retrieved from the response of a build-graph request).
The request UUID must be given in the request URL, e.g. request sent to */graph/temporal/75df6f8d-3829-4fd8-a3e6-b3e917010141*
* Response:
The response of this request is a JSON content, which contains the request UUID and the number of deleted nodes.
Returns a 404 Not Found error if the request UUID is not associated with any nodes in the graph.
* Response Body Example:
* Response Body Example:
```json
{
"uuid": "75df6f8d-3829-4fd8-a3e6-b3e917010141",
"deleted": 5
}
```
```
* **GET** ***/graph/temporal/{graph_id}/round-trip-time?compute_node={compute_node_id}&endpoint={endpoint_id}***
......@@ -163,15 +163,15 @@ It offers different API endpoints to configure and control the aggregator as wel
The response of this request is a JSON content, which contains the result from the Cypher query including forward latencies, reverse latencies and service function response time along with the
calculated round trip time and global tag values for the given service function endpoint.
Returns a 400 Bad Request error if the URL parameters are invalid
Returns a 404 Not Found error if the request UUID and the endpoint ID are not associated with an endpoint node in the graph.
Returns a 404 Not Found error if the compute node ID is not associated with a compute node in the graph.
* Response Body Example:
* Response Body Example:
```json
{
"request_size": 2048,
......@@ -198,13 +198,13 @@ It offers different API endpoints to configure and control the aggregator as wel
"host": "host2"
}
}
```
```
Here, the *forward_latencies* and *reverse_latencies* lists represent the latency experienced at each hop between compute nodes. For example, if the path was DC2-DC3-DC4 and the SF endpoint was hosted
on DC4, the response data shows that latency(DC2-DC3) = 22, latency(DC3-DC4) = 11, latency(DC4-DC3) = 15, latency(DC3-DC2) = 18, response_time(minio_1_ep1) = 15.75
N.B. if the endpoint is hosted on the compute node identified in the URL parameter, then there will be no network hops between compute nodes, so the latency lists would be empty, example:
```json
{
"request_size": 2048,
......@@ -227,22 +227,22 @@ It offers different API endpoints to configure and control the aggregator as wel
"host": "host2"
}
}
```
```
#### Aggregator API Endpoints
## Aggregator 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:
```json
{
"aggregator_report_period": 5,
......@@ -254,14 +254,14 @@ It offers different API endpoints to configure and control the aggregator as wel
* **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:
* Request Body Example:
```json
{
"aggregator_report_period": 25,
......@@ -269,14 +269,14 @@ It offers different API endpoints to configure and control the aggregator as wel
"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
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:
```json
{
"aggregator_report_period": 25,
......@@ -284,15 +284,15 @@ It offers different API endpoints to configure and control the aggregator as wel
"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:
```json
{
"aggregator_report_period": 125,
......@@ -306,22 +306,22 @@ It offers different API endpoints to configure and control the aggregator as wel
* **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:
```json
{
"aggregator_running": true
}
```
* Response Body Example - for malformed configuration:
```json
{
"aggregator_running": true,
......@@ -333,64 +333,64 @@ It offers different API endpoints to configure and control the aggregator as wel
* **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:
* Request Body Example:
```json
{
"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:
```json
{
"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.
#### CRUD API for service function endpoint configurations
## CRUD API for service function endpoint configurations
* **GET** ***/whoami/endpoints***
This API method retrieves all service function endpoint configurations in a JSON format.
* Response:
Returns a JSON-formatted response - a list of JSON objects, each object representing a service function endpoint configuration.
* Response Body Example:
- No service function endpoint configurations found.
```json
[]
```
- Multiple service function endpoint configurations found.
```json
[
......@@ -418,17 +418,17 @@ It offers different API endpoints to configure and control the aggregator as wel
* **GET** ***/whoami/endpoints/instance?sr={sr_id}&sf_i={sf_instance_id}&sf_endpoint={sf_endpoint_id}***
This API method retrieves the uniquely defined service function endpoint configuration associated with the given URL parameters - sr, sf_i and sf_endpoint.
* Response:
Returns a JSON-formatted response - a JSON object representing the service function endpoint configuration if it exists.
Returns a 404 Not Found error if there is no service function endpoint configuration associated with the given URL parameters.
Returns a 400 Bad Request error if the url parameters are invalid.
* Response Body Example:
- Request made to /whoami/endpoints/instance?sr=sr_1&sf_i=sf_i_1&sf_endpoint=sf_endpoint_1
```json
{
......@@ -445,12 +445,12 @@ It offers different API endpoints to configure and control the aggregator as wel
* **POST** ***/whoami/endpoints***
This API method creates a new service function endpoint configuration.
* Request:
Expects a JSON-formatted request body with the new service function endpoint configuration.
* Request Body Example:
* Request Body Example:
```json
{
......@@ -465,14 +465,14 @@ It offers different API endpoints to configure and control the aggregator as wel
```
* Response
Returns a JSON-formatted response - a JSON object representing the service function endpoint configuration that was created.
Returns a 400 Bad Request error if the request body is invalid.
Returns a 409 Conflict error if there exists another service function endpoint configuration with the same 'sr', 'sf_i' and 'sf_endpoint' values.
* Response Body Example:
* Response Body Example:
```json
{
......@@ -490,12 +490,12 @@ It offers different API endpoints to configure and control the aggregator as wel
This API method replaces the uniquely defined service function endpoint configuration associated with the given URL parameters - sr, sf_i and sf_endpoint with a new service
function endpoint configuration given in the request body (JSON format). It can also be used for updating.
* Request:
Expects a JSON-formatted request body with the new service function endpoint configuration.
* Request Body Example:
* Request Body Example:
```json
{
......@@ -510,18 +510,18 @@ It offers different API endpoints to configure and control the aggregator as wel
```
* Response
Returns a JSON-formatted response - a JSON object representing the new service function endpoint configuration that was created (updated).
Returns a 400 Bad Request error if the request body is invalid.
Returns a 400 Bad Request error if the url parameters are invalid.
Returns an 404 Not Found error if there is no service function endpoint configuration associated with the given URL parameters.
Returns a 409 Conflict error if there exists another service function endpoint configuration with the same 'sr', 'sf_i' and 'sf_endpoint' values as the ones in the request body.
* Response Body Example:
* Response Body Example:
- Request made to /whoami/endpoints/instance?sr=sr_1&sf_i=sf_i_1&sf_endpoint=sf_endpoint_1
```json
......@@ -539,17 +539,17 @@ It offers different API endpoints to configure and control the aggregator as wel
* **DELETE** ***/whoami/endpoints/instance?sr={sr_id}&sf_i={sf_instance_id}&sf_endpoint={sf_endpoint_id}***
This API method deletes the uniquely defined service function endpoint configuration associated with the given URL parameters - sr, sf_i and sf_endpoint.
* Response:
Returns the JSON representation of the deleted object.
Returns an 404 Not Found error if there is no service function endpoint configuration associated with the given URL parameters.
Returns a 400 Bad Request error if the url parameters are invalid.
* Response Body Example:
- Request made to /whoami/endpoints/instance?sr=sr_1&sf_i=sf_i_1&sf_endpoint=sf_endpoint_1
```json
{
......@@ -563,55 +563,56 @@ It offers different API endpoints to configure and control the aggregator as wel
}
```
#### Installing and running the CLMC service
## Installing and running the CLMC service
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.
```
```shell
pip3 install virtualenvwrapper
```
To create a virtual environment use the **mkvirtualenv** command:
```
```shell
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:
```
```shell
workon CLMC
```
Now, any installed libraries will be installed relative to this environment only.
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-service folder:
```
```shell
cd src/service
```
Test the CLMC service using **tox** along with the ***tox.ini*** configuration file. If tox is not installed run:
```
```shell
pip3 install tox
```
After it is installed, simply use the **tox** command:
```
```shell
tox
```
Then install the service.
```
```shell
pip3 install .
```
Finally, start the service on localhost by using pyramid's **pserve** command line utility:
```
```shell
pserve production.ini
```
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment