From 2b7bb5b5e82cf2699ef02e20ea31a04a80508dbe Mon Sep 17 00:00:00 2001
From: Jan David Mol <mol@astron.nl>
Date: Wed, 1 Jun 2022 16:19:10 +0200
Subject: [PATCH] Added explanation on how to add map panels and use locations
effectively
---
docs/source/monitoring.rst | 32 ++++++++++++++++++++++++++++++++
1 file changed, 32 insertions(+)
diff --git a/docs/source/monitoring.rst b/docs/source/monitoring.rst
index fddaeee..5cd699f 100644
--- a/docs/source/monitoring.rst
+++ b/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.
--
GitLab