diff --git a/docs/clmc-service.md b/docs/clmc-service.md
index 7879761b0f0ae283f852baa2559886c84cef1e7c..48e9c447fbe3c74c1a5d72761ea97da1b851bb47 100644
--- a/docs/clmc-service.md
+++ b/docs/clmc-service.md
@@ -25,13 +25,13 @@
#### **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
-This document describes the CLMC service and its API endpoints. The CLMC service is implemented in the *Python* framework called **Pyramid**.
+This document describes the CLMC service and its API endpoints. The CLMC service is implemented using the *Python* web framework called **Pyramid**.
It offers different API endpoints such as GraphAPI for calculating round trip time, CRUD API for service function endpoints
configuration data and Alerts API for creating and subscribing to alerts in Kapacitor. All source code, tests and
configuration files of the service can be found in the **src/service** folder.
@@ -47,21 +47,30 @@ configuration files of the service can be found in the **src/service** folder.
* Request:
- Expects a YAML-formatted file in the request referenced with ID ***alert-spec*** representing the alert specification
- document. This document is then parsed with the openstack TOSCA parser (https://github.com/openstack/tosca-parser/tree/master/toscaparser)
- and validated against the CLMC alerts specification schema (again check [documentation](AlertsSpecification.md) for more info on this).
+ Expects two YAML-formatted files in the request - one referenced with ID ***alert-spec*** representing the TOSCA alert specification
+ document and one referenced with ID ***resource-spec*** representing the TOSCA resource specification document.
+ The alert specification document is then parsed with the openstack TOSCA parser (https://github.com/openstack/tosca-parser/tree/master/toscaparser)
+ and validated against the CLMC alerts specification schema (again check [documentation](AlertsSpecification.md) for more info on this). The TOSCA resource
+ specification document is used only for consistency verification between the two documents - ensuring that they refer
+ to the same service function chain and service function chain instance, as well as making sure that there is at least one
+ trigger alert in the alerts specification that relates to a state change policy in the resources specification.
* Example for sending a request with curl:
- `curl -F "alert-spec=@alert-specification.yaml" http://loclahost:9080/alerts`
+ `curl -F "alert-spec=@alert-specification.yaml" -F "resource-spec=@resource-specification.yaml" http://loclahost:9080/alerts`
- where **alert-specification.yaml** is the path to the alerts specification file.
+ where **alert-specification.yaml** is the path to the alerts specification file and **resource-specification.yaml** is the
+ path to the resource specification file.
* Response:
The response of this request is a JSON-formatted content, which contains the SFC and SFC instance identifiers
from the alert specification along with any errors encountered when interacting with Kapacitor.
+ Returns a 400 Bad Request if the request does not contain a yaml file referenced with ID **resource-spec**.
+
+ Returns a 400 Bad Request if the resource specification file is not a TOSCA-compliant valid YAML file.
+
Returns a 400 Bad Request if the request does not contain a yaml file referenced with ID **alert-spec**.
Returns a 400 Bad Request if the alert specification file is not a valid YAML file.
@@ -70,6 +79,10 @@ configuration files of the service can be found in the **src/service** folder.
Returns a 400 Bad Request if the alert specification file fails validation against the CLMC alerts specification schema.
+ Returns a 400 Bad Request if there is inconsistencies between the alert specification and resource specification files -
+ e.g. referring to different service function chain and service function chain instance identifier or if there is no
+ alert in the alerts specification related to a given state change policy in the resources specification.
+
* Response Body Example:
```json
@@ -115,15 +128,14 @@ configuration files of the service can be found in the **src/service** folder.
* For each service function, there is a field/fields from which an average estimation of the size of a **request** to this service function can be derived.
* For each service function, there is a field/fields from which an average estimation of the size of a **response** from this service function can be derived.
* All the aforementioned fields reside in a single measurement.
- * There is at most 1 service function hosted on a particular endpoint.
* **POST** ***/graph/temporal?from={timestamp-seconds}&to={timestamp-seconds}***
- 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.
+ This API method sends a request to the CLMC service to build a graph related to the time range between the *from* and *to* timestamps (URL query 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.
+ Expects a JSON-formatted request body which declares the service function chain 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.
@@ -131,8 +143,7 @@ configuration files of the service can be found in the **src/service** folder.
```json
{
- "database": "MSDemo",
- "retention_policy": "autogen",
+ "service_function_chain": "MSDemo",
"service_function_chain_instance": "MSDemo_1",
"service_functions": {
"nginx": {
@@ -154,34 +165,34 @@ configuration files of the service can be found in the **src/service** folder.
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
+ SELECT {0} AS mean_response_time, {1} AS mean_request_size, {2} AS mean_response_size FROM "{3}"."{4}".{5} WHERE sfc=\'{6}\' and sfci=\'{7}\' and time>={8} and time<{9} GROUP BY sfe, location, sf
```
- 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):
+ 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
+ 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='MSDemo' and sfci='MSDemo_1' and time>=1528385420000000000 and time<1528385860000000000 GROUP BY sfe, location, sf
```
-
+
+ N.B. database name is assumed to be the SFC identifier
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.
+ 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:
```json
{
"database": "MSDemo",
"retention_policy": "autogen",
+ "service_function_chain": "MSDemo",
"service_function_chain_instance": "MSDemo_1",
"service_functions": {
"nginx": {
@@ -261,14 +272,13 @@ configuration files of the service can be found in the **src/service** folder.
"response_time": 15.75,
"round_trip_time": 81.75,
"global_tags": {
- "sr": "SR1",
- "ipendpoint": "minio_1_ep1",
+ "sfe": "minio_1_ep1",
"sfc": "MSDemo",
- "sf_i": "minio_1",
+ "sfci": "MSDemo_1",
+ "sfp": "minio",
+ "sf": "minio_1",
"location": "DC1",
- "sf": "minio",
- "sfc_i": "MSDemo_1",
- "host": "host2"
+ "server": "DC1"
}
}
```
@@ -290,167 +300,21 @@ configuration files of the service can be found in the **src/service** folder.
"response_time": 3,
"round_trip_time": 3,
"global_tags": {
- "sr": "SR1",
- "ipendpoint": "minio_1_ep1",
+ "sfe": "minio_1_ep1",
"sfc": "MSDemo",
- "sf_i": "minio_1",
+ "sfci": "MSDemo_1",
+ "sfp": "minio",
+ "sf": "minio_1",
"location": "DC1",
- "sf": "minio",
- "sfc_i": "MSDemo_1",
- "host": "host2"
- }
- }
- ```
-
-## Aggregator API Endpoints
-
-**Note: this API is deprecated. The graph API should be used to compute RTT instead.**
-
-* **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,
- "aggregator_database_name": "CLMCMetrics",
- "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:
-
- ```json
- {
- "aggregator_report_period": 25,
- "aggregator_database_name": "CLMCMetrics",
- "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:
-
- ```json
- {
- "aggregator_report_period": 25,
- "aggregator_database_name": "CLMCMetrics",
- "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,
- "aggregator_database_name": "CLMCMetrics",
- "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."
+ "server": "DC1"
}
- ```
-
-* **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,
- "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:
-
- ```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
-**Note: this API is experimental and is not intended to be used**
+**Note: this API is experimental and is not intended to be used at this stage**
* **GET** ***/whoami/endpoints***