Merge pull request #2 from 6G-SANDBOX/kpi_description

Kpi description

CHANGELOG.md

@@ -1,3 +1,7 @@
+**21/09/2023** [Version 3.6.2]
+ - Add a prefix (`/elcm/api/v1/`) to all endpoints
+ - Allow defining and return a more complete description of the KPIs in the `/elcm/api/v1/<id>/kpis` endpoint
+
 **09/11/2022** [Version 3.6.1]
  - Allow defining a set of KPIs per TestCase
  - Implement `/execution/<id>/kpis` endpoint

Facility/Loader/testcase_loader.py

@@ -25,7 +25,7 @@ class TestCaseLoader(Loader):
     testCases: Dict[str, List[ActionInformation]] = {}
     extra: Dict[str, Dict[str, object]] = {}
     dashboards: Dict[str, List[DashboardPanel]] = {}
-    kpis: Dict[str, List[Tuple[str, str]]] = {}
+    kpis: Dict[str, List[Tuple[str, str, str, str]]] = {}  # (Measurement, KPI, Type, Description)
     parameters: Dict[str, Tuple[str, str]] = {}  # For use only while processing data, not necessary afterwards
 
     @classmethod
@@ -100,10 +100,22 @@ def validateKPIs(cls, key: str, defs: TestCaseData) -> [(Level, str)]:
                         (Level.ERROR, f"KPIs for '{measurement}' ({key}) are not a list. Found '{kpiList}'"))
                 elif len(kpiList) == 0:
                     validation.append(
-                        (Level.ERROR, f"'{measurement}' ({key}) defines an empty listf of KPIs"))
+                        (Level.ERROR, f"'{measurement}' ({key}) defines an empty list of KPIs"))
                 else:
-                    for kpi in sorted(kpiList):
-                        kpis.append((measurement, kpi))
+                    for kpi in sorted(kpiList, key=lambda x: x if isinstance(x, str) else x.get('Name', '')):
+                        description = kind = ""
+                        if isinstance(kpi, str):
+                            name = kpi
+                        elif isinstance(kpi, dict):
+                            name = kpi.get('Name', '')
+                            description = kpi.get('Description', '')
+                            kind = kpi.get('Type', '')
+                        else:
+                            validation.append(
+                                (Level.ERROR, f"KPI definitions for '{measurement}' must either be str or a "
+                                              f"dictionary (keys ['Name', 'Type', 'Description']). Found '{kpi}'"))
+                            continue
+                        kpis.append((measurement, name, kind, description))
         except Exception as e:
             validation.append((Level.ERROR, f"Could not read KPIs dictionary for testcase '{key}': {e}"))
 

Facility/facility.py

@@ -24,7 +24,7 @@ class Facility:
     testCases: Dict[str, List[ActionInformation]] = {}
     extra: Dict[str, Dict[str, object]] = {}
     dashboards: Dict[str, List[DashboardPanel]] = {}
-    kpis: Dict[str, List[Tuple[str, str]]] = {}
+    kpis: Dict[str, List[Tuple[str, str, str, str]]] = {}
     resources: Dict[str, Resource] = {}
     scenarios: Dict[str, Dict] = {}
 
@@ -98,7 +98,7 @@ def GetTestCaseExtra(cls, id: str) -> Dict[str, object]:
         return cls.extra.get(id, {})
 
     @classmethod
-    def GetTestCaseKPIs(cls, id: str) -> List[Tuple[str, str]]:
+    def GetTestCaseKPIs(cls, id: str) -> List[Tuple[str, str, str, str]]:
         return cls.kpis.get(id, [])
 
     @classmethod

Scheduler/execution/routes.py

@@ -138,7 +138,14 @@ def kpis(executionId: int):
         for testcase in descriptor.TestCases:
             kpis.update(Facility.GetTestCaseKPIs(testcase))
 
-        return jsonify({"KPIs": sorted(kpis)})
+        res = []
+        for kpi in sorted(kpis):
+            measurement, name, kind, description = kpi
+            res.append({
+                'Measurement': measurement, 'KPI': name, 'Type': kind, 'Description': description
+            })
+
+        return jsonify({"KPIs": res})
     else:
         return f"Execution {executionId} not found", 404
 

docs/A1_ENDPOINTS.md

@@ -48,8 +48,17 @@ Returns a copy of the Experiment Descriptor that was used to define the executio
 
 ### [GET] `/elcm/api/v1/execution/<id>/kpis`
 
-Returns a dictionary with a single `KPIs` key, containing a list of pairs (`measurement`, `kpi`) that are considered of
-interest.
+Returns a dictionary with a single `KPIs` key, containing a list of objects that describe KPIs that are considered of
+interest. The objects have the following format:
+
+```text
+{ 
+    "Measurement": <Measurement (table) name>,
+    "KPI": <KPI name>,
+    "Type": <KPI group, may be an empty string>,
+    "Description": <Description of the KPI, may be an empty string>
+}
+```
 
 > These values can be used as part of queries to the [Analytics Module](https://github.com/5genesis/Analytics), in order
 > to extract a sub-set of important KPIs from all the generated measurements.