[QI2-1525] Add documentation on dynamic data reply

docs/request/meta.md

@@ -32,11 +32,11 @@ This message does not require any additional information in the payload section.
 | Key | Type | Value |
 | --- | --- | --- |
 | `nqubits` | `int` | The number of qubits |
-| `topology` | `list[tuple]` | List of the edges between the various qubits |
+| `topology` | `array[tuple]` | List of the edges between the various qubits |
 | `name` | `str` | Name of the system |
-| `pgs` | `list[str]` | Supported primitive gates set of the system. Gate names as described in cQASM (in uppercase) |
+| `pgs` | `array[str]` | Supported primitive gates set of the system. Gate names as described in cQASM (in uppercase) |
 | `starttime` | `float` | Timestamp of start-up of the system (return value of `time.time()`) |
-| `default_compiler_config` | `dict[str,list[dict[str, Any]]]` | Compiler configurations for different stages. |
+| `default_compiler_config` | `object[str,array[object[str, Any]]]` | Compiler configurations for different stages. |
 
 ### Get static reply example
 
@@ -71,7 +71,7 @@ This message does not require any additional information in the payload section.
 }
 ```
 
-##### Compiler configuration
+#### Compiler configuration
 
 The compiler configuration defines the pre-processing needed to convert the user-provided circuit into one that the
 backend can process. This comprises a list of steps that should be applied to the circuit using the Opensquirrel
@@ -117,21 +117,79 @@ This message does not require any additional information in the payload section.
 
 ### Get dynamic reply payload
 
-The payload for the message is still under advisement. The appropriate key-value pairs will be filled in when they are
-determined.
+The payload for this message contains an overview of one or more (or zero) metrics that can be used in a monitoring
+stack. In the table below, the format of a single metric is described. Keys between angular brackets (`<`) are dynamic.
 
 | Key | Type | Value |
 | --- | --- | --- |
-| - | - | - |
+| `<metric_name>` | object | Description of a single metric. The key is used as the metric name in Prometheus/Grafana. |
+| `__labels__` | array | The strings in this array are used as individual keys for labels in Prometheus/Grafana. |
+| `<label_value>` | any | The value can either be an object for nested values (see example 2), or an `int` or `float` for a leaf. The value of the (recursive) key is mapped by index to the labels in `__labels__` (e.g. `key1=q1` and `key2=x1`). The tree is traversed until a leaf is found. This value is interpreted as the value for the metric. If there is no value for the specific instance `null` can be reported, or the branch can be ommitted. |
 
-### Get dynamic reply example
+The reason that these labels are this important has to do with the aggregation and filtering of metrics. By specifying
+one metric which is measured for different data point, the dashboard can easily reference this metric. However, if
+necessary panels in the dashboard or alerts can also reference values for individual data points.
+
+### Get dynamic reply example 1: No labels
+
+```json title="get_dynamic_reply.json" linenums="1"
+{
+    "status": "success",
+    "payload": {
+        "fridge_temperature_in_mk": 8.4
+    },
+    "version": "0.2.0"
+}
+```
+
+This will be represented in Prometheus/Grafana as:
+
+```txt
+qi_fridge_temperature_in_mk 8.4
+```
+
+### Get dynamic reply example 2: One label
+
+```json title="get_dynamic_reply.json" linenums="1"
+{
+    "status": "success",
+    "payload": {
+        "t1": {
+            "__labels__": ["qubit"],
+            "q0": 0.995,
+            "q1": 0.988
+        }
+    },
+    "version": "0.2.0"
+}
+```
+
+This will be represented in Prometheus/Grafana as:
+
+```txt
+qi_t1{qubit=q0} 0.995
+qi_t1{qubit=q1} 0.988
+```
+
+### Get dynamic reply example 2: Multiple labels
 
 ```json title="get_dynamic_reply.json" linenums="1"
 {
     "status": "success",
     "payload": {
-        // to be determined
+        "cnot_fidelity": {
+            "__labels__": ["qubit1", "qubit2"],
+            "q1": {
+                "q0": 0.995
+            }
+        }
     },
     "version": "0.2.0"
 }
 ```
+
+This will be represented in Prometheus/Grafana as:
+
+```txt
+qi_cnot_fidelity{qubit1=q1, qubit2=q0} 0.995
+```