From 36111867d6c18a904fd8621b7f4c0913f0237a69 Mon Sep 17 00:00:00 2001
From: Nikolay Stanchev <ns17@it-innovation.soton.ac.uk>
Date: Tue, 10 Jul 2018 12:56:19 +0100
Subject: [PATCH] Documents the Graph API of the CLMC service
---
docs/clmc-service.md | 148 ++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 147 insertions(+), 1 deletion(-)
diff --git a/docs/clmc-service.md b/docs/clmc-service.md
index 6b767d9..9040d06 100644
--- a/docs/clmc-service.md
+++ b/docs/clmc-service.md
@@ -35,6 +35,152 @@ 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.
All source code, tests and configuration files of the service can be found in the **src/service** folder.
+
+#### Graph API Endpoints
+
+* **POST** ***/graph/build?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.
+
+ * 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 and response time field for each
+ service function. The response time field could be an influx function across multiple fields.
+
+ * Request Body Example:
+
+ ```json
+ {
+ "database": "MSDemo",
+ "retention_policy": "autogen",
+ "service_function_chain_instance": "MSDemo_1",
+ "service_functions": {
+ "nginx": {
+ "response_time_field": "mean(response_time)",
+ "measurement_name": "nginx"
+ },
+ "minio": {
+ "response_time_field": "mean(sum)/mean(count)",
+ "measurement_name":"minio_http_requests_duration_seconds"
+ }
+ }
+ }
+ ```
+
+ These parameters are then filled in the following influx query template:
+
+ ```
+ SELECT {0} AS mean_response_time FROM "{1}"."{2}".{3} WHERE sfc_i='{4}' and time>={5} and time<{6} 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 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.
+
+ * Response Body Example:
+
+ ```json
+ {
+ "database": "MSDemo",
+ "retention_policy": "autogen",
+ "service_function_chain_instance": "MSDemo_1",
+ "service_functions": {
+ "nginx": {
+ "response_time_field": "mean(response_time)",
+ "measurement_name": "nginx"
+ },
+ "minio": {
+ "response_time_field": "mean(sum)/mean(count)",
+ "measurement_name":"minio_http_requests_duration_seconds"
+ }
+ },
+ "graph": {
+ "uuid": "75df6f8d-3829-4fd8-a3e6-b3e917010141",
+ "time_range": {
+ "from": 1528385420,
+ "to": 1528385860
+ }
+ }
+ }
+ ```
+
+* **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:
+
+ ```json
+ {
+ "uuid": "75df6f8d-3829-4fd8-a3e6-b3e917010141",
+ "deleted": 4
+ }
+ ```
+
+* **GET** ***/graph/temporal/{graph_id}/round-trip-time?compute_node={compute_node_id}&endpoint={endpoint_id}***
+
+ This API method sends a request to run the Cypher Round-Trip-Time query over a temporal graph associated with a 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/round-trip-time?compute_node=DC2&endpoint=minio_1_ep1*
+
+ * Response:
+
+ 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.
+
+ 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:
+
+ ```json
+ {
+ "forward_latencies": [
+ 22, 11
+ ],
+ "reverse_latencies": [
+ 15, 18
+ ],
+ "response_time": 15.75
+ }
+ ```
+
+ 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
+ {
+ "forward_latencies": [],
+ "reverse_latencies": [],
+ "response_time": 15.75
+ }
+ ```
+
+
#### Aggregator API Endpoints
* **GET** ***/aggregator/config***
@@ -228,7 +374,7 @@ All source code, tests and configuration files of the service can be found in th
Returns a JSON-formatted response - a JSON object representing the service function endpoint configuration if it exists.
- Returns an 404 Not Found error if there is no service function endpoint configuration associated with the given URL parameters.
+ 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.
--
GitLab