Ping metrics (#23)

* Add /devices/{id}/statistics path to Swagger config

This is in preparation to fetch ping statistics from UNMS. The endpoint
returns A LOT more data, but for now this contains only the minimal set.

* Add ping metrics

This enables fetching device statistics from UNMS, extracting
the ping RTT values from it, and export them back to prometheus.

Since fetching statistics requires talking to another, device-specific
endpoint, the context timeout is increased from 5 to 30s. A future
change should pass the request context from the promhttp endpoint
down to the fetchDeviceData() method, to make the timout depend on
Prometheus' scrape request life cycle.

* Ping metrics: disable by default, add config knob

* Ping metrics: update README

* Make examples in README consistent

* Ping metrics: cleanup dead code

* Ping metrics: add tests for env vars/CLI flags

* Allow usage of dash in metrics option

* Update docs and extend test case

Co-authored-by: Marcus Weiner <marcus.weiner@gmail.com>

README.md

@@ -45,19 +45,89 @@ Log verbosity level. Defaults to `info`. Use `debug` to get more details.
 
 Configures an API token per UNMS instance.
 
-Example:
+<details><summary>Example: config file (click to open)</summary>
 
 ```yaml
+# config.yaml
 token:
   my-unms-instance.example.org: "my token"
   unms.example.com: "token123"
 ```
 
+```console
+$ unms-exporter --config config.yaml
+```
+
+</details>
+<details><summary>Example: environment variable (click to open)</summary>
+
 ```console
 $ UNMS_EXPORTER_TOKEN="my-unms-instance.example.org=my token,unms.example.com=token123" \
     unms-exporter
 ```
 
+</details>
+
+### Extra metrics
+
+- Config: `extra_metrics` (as Array)
+- Args: `--extra-metrics` (as comma-separated list)
+- Env: `UNMS_EXPORTER_EXTRA_METRICS` (as comma-separated list)
+
+Enable additional metrics to be exported. These metrics may require extra
+HTTP requests, usually one per device, so they are disabled by default.
+
+<details><summary>Example: config file (click to open)</summary>
+
+```yaml
+# config.yaml
+extras:
+- ping
+```
+
+```console
+$ unms-exporter --config config.yaml
+```
+
+</details>
+<details><summary>Example: environment variable (click to open)</summary>
+
+```console
+$ UNMS_EXPORTER_EXTRA_METRICS="ping" \
+    unms-exporter
+```
+
+</details>
+<details><summary>Example: command line argument (click to open)</summary>
+
+```console
+$ unms-exporter --extra-metrics="ping"
+```
+
+</details>
+
+#### Available metrics
+
+- `ping`: Fetch statistical data from UNMS and extract and export
+  Ping RTT measurements between UNMS and the device.
+
+  <details><summary>Exported metrics (click to open)</summary>
+
+  - `ping_loss_ratio`: Packet loss ratio (range 0-1, with 0.33 meaning 33% packet loss)
+  - `ping_rtt_best_seconds`: Best round trip time, in seconds
+  - `ping_rtt_mean_seconds`: Mean round trip time, in seconds
+  - `ping_rtt_worst_seconds`: Worst round trip time, in seconds
+  - `ping_rtt_std_deviation_seconds`: Standard deviation for round trip time, in seconds
+
+  </details>
+
+Further data is available, but not currently exported (see the API
+documentation for the `/devices/{id}/statistics` endpoint on your UNMS
+installation to get an overview). Feel free to [open a new issue][] to
+inquire whether an integration into the exporter is feasable.
+
+[open a new issue]: https://github.com/ffddorf/unms-exporter/issues/new
+
 ## Prometheus Scrape Setup
 
 The exporter follows the convention for exporters. The UNMS instance to target should be specified using the `target` query parameter.