typos and minor fix to some sentences

fix controls descriptions fix sections order improve latest description explain datatype difference between integer and filesize
weaveworks · Feb 20, 2017 · c6f0244 · c6f0244
1 parent 67d1cb2
commit c6f0244
Showing 1 changed file with 65 additions and 56 deletions.
diff --git a/site/plugins.md b/site/plugins.md
@@ -426,9 +426,10 @@ The available topologies are:
 The topology structure consists of the following attributes:
 
 - `nodes` - is the list of the nodes that compose the topology.
-- `controls` - contains the description of the controls that apply to the specific topology.
+- `controls` - contains the list of IDs of the active controls at a particular time.
 - `metadata_templates` - contains the templates used to render data into the Scope UI.
 - `table_templates` - contains the templates used to render tables into the Scope UI.
+- `metric_templates` - contains the templates used to render metrics into the Scope UI.
 
 **Note**: These attribute are not required. But a topology with no `nodes` does not have any information to render, `metadata_templates`, as well as `table_templates`, are needed to know how to render the information carried by `nodes` in the Scope UI.
 
@@ -454,20 +455,26 @@ Nodes are represented as follows:
 }
 ```
 
-Nodes are stored in dictionary. The ID of nodes representing hosts or containers have the format `ID;<type>`, with type equal `host` or `container` accordingly.
-
+Nodes are stored in dictionary. The ID of nodes representing hosts or containers have the format `ID;<type>`, with type equal to the literal string `host` or `container` accordingly. The `ID` is the alphanumeric identifier of the nodes.
 A node contains all the information about the represented object (e.g. host, container, pod, etc.).
 In particular a node may contain:
 
-- `latest` - the latest values to display.
+- `latest` - an id-value map containing the latest values. These values are a single piece of information.
 - `latestControls` - the latest available controls.
 - `metrics` - the collection of metrics to display in the UI.
 
 ### Controls
 Controls describe interfaces that expose actions that the user can perform on different objects (e.g. host, container, etc.).
 Controls are an element of nodes. In this way, each control in a node is attached to it and performs an action on the object described by the node itself. Below is an example of how controls are represented in the JSON report.
+In the report the attribute `latest_controls` contains all the controls exposed by scope and/or plugins, but only the alive ones will be listed in the attribute `controls`.
 
 ```json
+"controls": {
+	"timestamp": "2016-11-17T08:53:04.567890059Z",
+	"controls": [
+		"switchToIOWait"
+	]
+},
 "latestControls": {
 	"switchToIOWait": {
 		"timestamp": "2016-11-17T08:53:03.171438309Z",
@@ -482,21 +489,46 @@ Controls are an element of nodes. In this way, each control in a node is attache
 		}
 	}
 }
-``` 
+```
 
 - `timestamp` is the timestamp of when the control was exposed.
 - `value` is an object containing the control value. At the moment, only the state is available.
- - `Dead` is a boolean to know the state (active, dead) of a control. It is useful to show controls only when they are in a usable state.
+ - `dead` is a boolean to know the state (active, dead) of a control. It is useful to show controls only when they are in a usable state.
+
+### Metadata
+All metadata entries are placed within nodes in the section named `latest`.
+This section contains the latest values to display and consists of `timestamp` and `value`.
+Scope uses `metadata_templates` to know how to display such data.
+To pair metadata with its template, it is necessary to use the `metadata-template-id` as a key to identify that particular piece of data. Example:
+
+```json
+"metadata-templates": {
+      "metadata-templates-id": {
+        "id": "metadata-templates-id",
+        "label": "Human-readable description",
+        "priority": 1.6,
+        "from": "latest"
+      }
+}
+
+"latest": {
+	"metadata-templates-id": {
+		"timestamp": "2016-11-17T08:53:02.189193735Z",
+		"value": "-"
+	}
+}
+```
 
 ### Metadata Templates
-Metadata Templates describe of a particular metadata.
+Metadata Templates describe a particular metadata item.
 This description is used to extract metadata from a node and display it on Scope UI.
 
 ```json
 "metadata_templates": {
       "metadata-template-id": {
         "id": "metadata-template-id",
         "label": "Human-readable description",
+        "datatype": "number",
         "priority": 13.5,
         "from": "latest"
       },
@@ -506,7 +538,8 @@ This description is used to extract metadata from a node and display it on Scope
 
 - `metadata-template-identifier` and `id` identify a particular metadata template.
 - `label` contains the label that will be used by Scope UI.
-- `priority` is a floating point value used to decide the display ordering (lower values are displayed before higher ones).
+- `datatype` specifies the type of data, this will determine how the value is displayed. Possible values for this attribute are: number, ip, and datetime.
+- `priority` is a floating point value used to decide the display ordering (lower values are displayed before higher ones). If it is omitted the UI display the value as last.
 - `from` indicates where to look for the metadata. The possible values are:
  - `latest`
  - `sets`
@@ -532,54 +565,6 @@ Table Templates describe a table and how to identify which metadata templates be
 
 If you want to display data in a table, you have to define a table template and prepend the table prefix to all the metadata templates that identifies the data you want to put in such table.
 
-### Metric Templates
-Metric Templates describe a particular metric.
-The following is an example of metric template:
-
-```json
-"metric_templates": {
-      "metric-template-id": {
-        "id": "metric-id",
-        "label": "Human-readable description",
-        "format": "percent",
-        "priority": 1.6
-      },
-      "another-metric-template-id": {...}
-}
-```
-
-- `metric-template-id` and `id` identify a particular metric template.
-- `label` contains the label that will be used by Scope UI.
-- `format` describes who the metrics is formatted.
- - `percent` the metric value is a percentage.
- - `filesize` the metric value is a file size (e.g. memory usage).
- - `integer` the metric value is an integer.
-- `priority` is a floating point value used to decide the display ordering (lower values are displayed before higher ones).
-
-### Metadata
-All metadata entries are placed within nodes in the section named `latest`.
-This section contains the latest values to display and consists of `timestamp` and `value`.
-Scope uses `metadata_templates` to know how to display such data.
-To pair metadata with its template, it is necessary to use the `metadata-template-id` as a key to identify that particular piece of data. Example:
-
-```json
-"metadata-templates": {
-      "metadata-templates-id": {
-        "id": "metadata-templates-id",
-        "label": "Human-readable description",
-        "priority": 1.6,
-        "from": "latest"
-      }
-}
-
-"latest": {
-	"metadata-templates-id": {
-		"timestamp": "2016-11-17T08:53:02.189193735Z",
-		"value": "-"
-	}
-}
-```
-
 ### Metrics
 Metrics are a particular kind of data that can be plotted on the UI as a graph.
 Scope uses the `metric_templates` to know how to display such data. To pair a metric with its template, it is necessary to use the `metric-template-id` as key to identify that particular metric.
@@ -614,6 +599,30 @@ The following is an example of a report with a metric and a its metric template:
 - `min` is the minimum value possible.
 - `max` is the maximum value possible.
 
+### Metric Templates
+Metric Templates describe a particular metric.
+The following is an example of metric template:
+
+```json
+"metric_templates": {
+      "metric-template-id": {
+        "id": "metric-id",
+        "label": "Human-readable description",
+        "format": "percent",
+        "priority": 1.6
+      },
+      "another-metric-template-id": {...}
+}
+```
+
+- `metric-template-id` and `id` identify a particular metric template.
+- `label` contains the label that will be used by Scope UI.
+- `format` describes how the metrics is formatted.
+ - `percent` the metric value is a percentage.
+ - `filesize` the metric value is a file size (e.g. memory usage), it is displayed with the suffix KB, MB, GB, etc.
+ - `integer` the metric value is an integer.
+- `priority` is a floating point value used to decide the display ordering (lower values are displayed before higher ones).
+
 ### Time Window
 A report may have an attribute called `Window`.
 This is the time window, expressed as duration, within which the data contained in the report are considered valid.