From a177cdea3cb5175d7c318f9a69d157e779ce902b Mon Sep 17 00:00:00 2001
From: Massaki Archambault <badjware@massaki.ca>
Date: Sun, 26 Sep 2021 13:46:12 -0400
Subject: [PATCH] readme

---
 README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 58 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index d2e5860..1d3981e 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,59 @@
-# helium-blockchain-exporter
+# Helium blockchain exporter
+[![Build Status](https://drone.badjware.dev/api/badges/badjware/helium-blockchain-exporter/status.svg)](https://drone.badjware.dev/badjware/helium-blockchain-exporter)
 
-Export helium blockchain data to prometheus.
\ No newline at end of file
+Export helium blockchain data from the [helium blockchain API](https://docs.helium.com/api/blockchain/introduction/) to [prometheus](https://prometheus.io).
+
+If an helium account address is supplied, export metrics from this account and all the hotspots owned by them.
+
+## Usage
+
+A docker image is available on [badjware/helium-blockchain-exporter](https://hub.docker.com/repository/docker/badjware/helium-blockchain-exporter). By default, the exporter listen on port 9865.
+
+The address of an account can be supplied with the `-accounts` flag. If you wish to export metrics from multiple accounts, you can supply a list of accounts by delimiting them with a comma. If no accounts are supplied, only generic blockchain stats will be exported.
+
+Eg:
+``` sh
+docker run -p 9865:9865 badjware/helium-blockchain-exporter -accounts=14YeKFGXE23yAdACj6hu5NWEcYzzKxptYbm5jHgzw9A1P1UQfMv
+```
+The same, but for docker-compose:
+``` yaml
+version: "3"
+services:
+  helium-blockchain-exporter:
+  image: badjware/helium-blockchain-exporter
+    ports:
+      - "9865:9865"
+    args:
+      - -acounts=14YeKFGXE23yAdACj6hu5NWEcYzzKxptYbm5jHgzw9A1P1UQfMv
+```
+
+Metrics will be available on http://localhost:9865/metrics.
+
+Run the exporter with the `-h` flag for a full list of available flags.
+
+### Scape config considerations
+
+Each time a query is made to the */metrics* of the exporter, the data is queried from the helium api. The api can take a few seconds to reply, so it's recommended to set the `scrape_timeout` in your prometheus configuration to a higher value that the default to avoid timeouts, eg: `30s`. 
+
+Currently, the block time on the helium blockchain is about 60 seconds per blocks. It's useless to scrape the chain faster than this rate. For this reason, it's recommended to set the `scrape_interval` in your prometheus configuration to at least `60s`.
+
+The helium api might occasionally be unreliable. In the event that the exporter is unable to get a valid answer from the api, the metric will be omitted from the */metrics*. The metrics that where successfully queried will still be exposed. This must be kept in mind when creating dashboards and alerts using these metrics.
+
+### Gafana dashboard
+
+### Alerts
+
+## Building for development
+
+Clone this repository and run `make`. The binary will be in *./bin/*. To build and run the exporter:
+```
+make && ./bin/helium-blockchain-exporter
+```
+
+To build the docker image:
+``` sh
+make docker
+```
+
+## Future versions
+* Add validator metrics
\ No newline at end of file