docs: add running instructions

README.md

@@ -1,3 +1,38 @@
 # blobstreamx-monitor
 
-Simple monitoring tool for BlobstreamX contract
+Simple monitoring tool for BlobstreamX contract. It allows provers/relayers for BlobstreamX to monitor the BlobstreamX updates, and be notified.
+
+The tool currently sends an OTEL message whenever a new batch is submitted, verified and committed by the contract. This message is a counter `blobstreamx_monitor_submitted_nonces_counter` of type `Int64Counter`.
+
+## Install
+
+1. [Install Go](https://go.dev/doc/install) 1.21
+2. Clone this repo
+3. Install the BlobstreamX-monitor CLI
+
+ ```shell
+make install
+```
+
+## Usage
+
+```sh
+# Print help
+blobstreamx-monitor --help
+```
+
+## How to run
+
+To run the monitoring tool, make sure you have access to an [otel collector](https://opentelemetry.io/docs/collector/installation/), by default it targets the `"localhost:4318"` endpoint:
+
+```shell
+blobstreamx-monitor start \
+  --evm.rpc <evm_chain_rpc> \
+  --evm.contract-address <blobstreamx_contract_address> \
+  --metrics.endpoint <otel_collector_endpoint> \
+  --log.level debug
+```
+
+To start a local monitoring environment, refer to the example setup in the `example` folder that spins up an otel collector, prometheus and grafana which can be used to check the above metric from BlobstreamX contract.
+
+After running the tool, operators can setup alerts to alarm them if there is a BlobstreamX liveness issue and begin investigating running backup provers.

example/docker-compose.yml

@@ -0,0 +1,45 @@
+version: '3'
+
+services:
+  prometheus:
+    container_name: prometheus
+    image: prom/prometheus
+    ports:
+      - "9000:9090"
+    volumes:
+      - ${PWD}/telemetry/prometheus:/etc/prometheus
+      - prometheus-data:/prometheus
+    command: --web.enable-lifecycle  --config.file=/etc/prometheus/prometheus.yml
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+
+  otel-collector:
+    container_name: otel-collector
+    image: otel/opentelemetry-collector
+    command: ["--config=/root/otel-collector/config.yml"]
+    volumes:
+      - ${PWD}/telemetry/otel-collector:/root/otel-collector/
+    ports:
+      - "8888:8888"   # Prometheus metrics exposed by the collector
+      - "8889:8889"   # Prometheus exporter metrics
+      - "55681:55681"
+      - "13133:13133"  # health_check extension
+      - "4317:4317"   # OTLP gRPC receiver
+      - "4318:4318"   # OTLP http receiver
+      - "4319:4319"   # OTLP http receiver
+
+  grafana:
+    container_name: grafana
+    image: grafana/grafana:latest
+    user: "0"
+    ports:
+      - 3001:3000
+    restart: unless-stopped
+    volumes:
+      - ${PWD}/telemetry/grafana/:/etc/grafana/provisioning/
+      - ${PWD}/telemetry/grafana/:/var/lib/grafana/dashboards/
+      - grafana-data:/var/lib/grafana
+
+volumes:
+  prometheus-data:
+  grafana-data:

example/telemetry/grafana/datasources/config.yml

@@ -0,0 +1,9 @@
+---
+apiVersion: 1
+
+datasources:
+  - name: Prometheus
+    type: prometheus
+    access: proxy
+    url: http://prometheus:9090
+

example/telemetry/otel-collector/config.yml

@@ -0,0 +1,24 @@
+---
+extensions:
+  health_check:
+
+receivers:
+  otlp:
+    protocols:
+      grpc:
+      # endpoint: "0.0.0.0:4317"
+      http:
+      # endpoint: "0.0.0.0:4318"
+
+exporters:
+  prometheus:
+    endpoint: "otel-collector:8889"
+    send_timestamps: true
+    metric_expiration: 1800m
+
+service:
+  extensions: [health_check]
+  pipelines:
+    metrics:
+      receivers: [otlp]
+      exporters: [prometheus]

example/telemetry/prometheus/prometheus.yml

@@ -0,0 +1,16 @@
+---
+global:
+  scrape_interval: 15s
+  scrape_timeout: 10s
+  evaluation_interval: 15s
+
+scrape_configs:
+  - job_name: 'collector'
+    metrics_path: /metrics
+    honor_timestamps: true
+    scrape_interval: 15s
+    scrape_timeout: 10s
+    scheme: http
+    static_configs:
+      - targets:
+          - 'otel-collector:8889'