Added explanation on how to add map panels and use locations effectively

docs/source/monitoring.rst

@@ -94,3 +94,35 @@ This software stack itself also exposes metrics from its various services:
 :go\_\*, grafana\_\*: Metrics from Grafana, see https://grafana.com/docs/grafana/latest/administration/view-server/internal-metrics/ and https://grafana.com/docs/grafana/latest/alerting/unified-alerting/fundamentals/evaluate-grafana-alerts/.
 
   :job:          `grafana`
+
+Map Panels
+------------------------------------
+
+Grafana provides panels to display points on a map, where both the locations of the pins and their colours are drawn from the database. We use the `Orchestra Cities Map <https://grafana.com/grafana/plugins/orchestracities-map-panel/>`_ plugin for the best results.
+
+The position information is best used in the `Geohash <https://www.pubnub.com/learn/glossary/what-is-geohashing/>`_ format, which encodes latitude and longitude as a single string. The station exposes the following geohash positions as attributes::
+
+  # Position of each HBAT
+  device_attribute{host="$station", device="stat/antennafield/1", name="HBAT_reference_GEOHASH_R"}
+
+  # Position of each Antenna Field
+  device_attribute{host="$station", device="stat/antennafield/1", name="Antenna_Field_Reference_GEOHASH_R"}
+
+To use these in the Orchestra map, you need to configure the *Data Layer* as follows:
+
+* Set `Location` to `Geohash`,
+* Set `Geohash field` to `str_value`.
+
+Furthermore, you will want to consider:
+
+* `Base layer` to `Open Street Map`,
+* `Map view` -> `Initial view` -> `View` to `Auto Center`,
+
+To add *colours* for each dot, we need to combine the position with the value of another metric, for example::
+
+  sum by (host, x) (device_attribute{host="$station", device="stat/antennafield/1", name="HBAT_PWR_on_R"})
+  + on(host, x) group_right() (device_attribute{host="$station", device="stat/antennafield/1", name="HBAT_reference_GEOHASH_R"} * 0)
+
+In which `HBAT_PWR_on_R` represents the power of an HBAT element, which we sum per tile over all elements using `sum by (host, x)`. The output of this, the first line, will determine the colour. The position is added by using `group_by`, which adds the critical `str_value` of the `HBAT_reference_geohash_R`. By using `+ on(...) (... * 0)`, we make sure the metric value is not influenced by the value of the geohash metric.
+
+The colour is configured in the *Data Layer* by setting `Marker Color` to `Value`, and configuring the `Thresholds` at the bottom for the actual colour to be used for each range of values.