readme

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.
+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