Skip to content

Commit d90ec9a

Browse files
rayanebelrayanebel
authored
Merge pull request #10 from kilnfi/docs/update-readme
docs: update docs
2 parents 2af75a4 + 9926607 commit d90ec9a

File tree

3 files changed

+295
-1
lines changed

3 files changed

+295
-1
lines changed

‎README.md

Lines changed: 257 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,257 @@
1-
# cardano-validator-watcher
1+
# Cardano Validator Watcher
2+
3+
**Cardano Validator Watcher** is a Prometheus exporter designed to help you monitor your Cardano validator nodes. It periodically collects essential metrics, providing valuable insights into the performance and health of your infrastructure. These exported metrics can be used to build monitoring dashboards _(e.g with Grafana)_ and configure alerting rules to stay notified when something goes wrong.
4+
5+
<img src="./docs/images/banner.jpg" alt="banner" style="width:100%;">
6+
7+
## Dependencies
8+
9+
This project use the following dependencies:
10+
11+
- [BlockFrost](https://blockfrost.dev/). You need to have a account and a subscription.
12+
- [cncli](https://github.com/cardano-community/cncli) to calculate the slot leaders.
13+
- [cardano-cli](https://github.com/IntersectMBO/cardano-cli) to query additional data from a RPC node.
14+
15+
## Usage
16+
17+
```bash
18+
./cardano-validator-watcher [flags]
19+
```
20+
### Flags
21+
22+
| Flag | Description | Default Value | Required |
23+
|---------------------------------------|---------------------------------------------------------------------------------------|---------------------------|----------|
24+
| `--config` | Path to the configuration file | `config.yml` | No |
25+
| `--log-level` | Log Level | `info` | No |
26+
| `--http-server-host` | Host on which the HTTP server should listen | `127.0.0.1` | No |
27+
| `--http-server-port` | Port on which the HTTP server should listen | `8080` | No |
28+
| `--network` | Cardano network ID | `preprod` | Yes |
29+
| `--database-path` | Path to the local database mainly used by the Cardano client | `watcher.db` | No |
30+
| `--cardano-config-dir` | Path to the directory where Cardano configuration files are stored | `/config` | No |
31+
| `--cardano-timezone` | Timezone to use with cardano-cli | `UTC` | No |
32+
| `--cardano-socket-path` | Path of the socket to communicate with a Cardano node | `/var/run/cardano.socket` | No |
33+
| `--blockfrost-project-id` | Blockfrost project ID | | Yes |
34+
| `--blockfrost-endpoint` | Blockfrost API endpoint | | Yes |
35+
| `--blockfrost-max-routines` | Number of routines used by Blockfrost to perform concurrent actions | `10` | No |
36+
| `--blockfrost-timeout` | Timeout for requests to the Blockfrost API (in seconds) | `60` | No |
37+
| `--block-watcher-enabled` | Enable block watcher | `True` | No |
38+
| `--block-watcher-refresh-interval` | Interval at which the block watcher collects and processes slots (in seconds) | `60` | No |
39+
| `--pool-watcher-enabled` | Enable pool watcher | `True` | No |
40+
| `--pool-watcher-refresh-interval` | Interval at which the pool watcher collects data on monitored pools (in seconds) | `60` | No |
41+
| `--network-watcher-enabled` | Enable network watcher | `True` | No |
42+
| `--network-watcher-refresh-interval` | Interval at which the network watcher collects data related to network (in seconds) | `60` | No |
43+
| `--status-watcher-refresh-interval` | Interval at which the status watcher collects data related to health (in seconds) | `15` | No |
44+
45+
## Configuration
46+
47+
The watcher uses a `config.yaml` file in the current working directory by default. Use the `--config` flag to specify a different configuration file.
48+
49+
### Full Example
50+
51+
```yaml
52+
pools:
53+
- instance: "cardano-producer-xxxx-0"
54+
id: "poolxxxxxxxxxxxx"
55+
name: "xxxx-0"
56+
key: "config/xxxx.vrf.skey"
57+
- instance: "cardano-producer-xxxx-1"
58+
id: "poolxxxxxxxxxxxx"
59+
name: "xxxx-1"
60+
key: "config/xxxxx-1.vrf.skey"
61+
exclude: true
62+
allow-empty-slots: true
63+
network: "mainnet"
64+
block-watcher:
65+
enabled: true
66+
refresh-interval: 30
67+
pool-watcher:
68+
enabled: true
69+
refresh-interval: 30
70+
network-watcher:
71+
enabled: true
72+
refresh-interval: 30
73+
status-watcher:
74+
enabled: true
75+
refresh-interval: 15
76+
database:
77+
path: "watcher.db"
78+
blockfrost:
79+
project-id: "thisissecret"
80+
endpoint: "https://cardano-mainnet.blockfrost.io/api/v0"
81+
max-routines: 10
82+
timeout: 60
83+
http:
84+
host: "0.0.0.0"
85+
port: 8080
86+
cardano:
87+
config-dir: "config"
88+
socket-path: "/tmp/cardano.socket"
89+
timezone: "UTC"
90+
```
91+
92+
### Pools Settings
93+
94+
| Field | Description | Example |
95+
|---------------------------|-----------------------------------------------------------|---------------------------------------------------------------------|
96+
| `instance` | Name of the instance | `"mainnet-cardano-producer-kiln-0"` |
97+
| `id` | Pool ID | `"pool10rdglgh4pzvkf936p2m669qzarr9dusrhmmz9nultm3uvq4eh5k"` |
98+
| `name` | Name of the pool | `"kiln-0"` |
99+
| `key` | Path to the key file | `"config/kiln-0.vrf.skey"` |
100+
| `exclude` | Exclude the pool from monitoring | `true` |
101+
| `allow-empty-slots` | Pools is allowed to not have slot leaders | `"config/kiln-0.vrf.skey"` |
102+
103+
```yaml
104+
pools:
105+
- instance: "cardano-producer-xxxx-0"
106+
id: "poolxxxxxxxxxxxx"
107+
name: "xxxx-0"
108+
key: "config/xxxx.vrf.skey"
109+
- instance: "cardano-producer-xxxx-1"
110+
id: "poolxxxxxxxxxxxx"
111+
name: "xxxx-1"
112+
key: "config/xxxxx-1.vrf.skey"
113+
exclude: true
114+
allow-empty-slots: true
115+
```
116+
117+
### Global Settings
118+
119+
| Field | Description | Example |
120+
|------------|-------------------------|---------------|
121+
| `network` | Name of the network | `"mainnet"` |
122+
123+
```yaml
124+
network: "mainnet"
125+
```
126+
127+
### Block Watcher Settings
128+
129+
| Field | Description | Example |
130+
|-----------------------|-------------------------------------------------------------------------|-----------|
131+
| `enabled` | Enable block watcher | `True` |
132+
| `refresh-interval` | Time, in seconds, between two consecutive collections of block data | `60` |
133+
134+
```yaml
135+
block-watcher:
136+
enabled: true
137+
refresh-interval: 30
138+
```
139+
140+
### Pool Watcher Settings
141+
142+
| Field | Description | Example |
143+
|-----------------------|-------------------------------------------------------------------------|-----------|
144+
| `enabled` | Enable pool watcher | `True` |
145+
| `refresh-interval` | Time, in seconds, between two consecutive collections of pool data | `60` |
146+
147+
```yaml
148+
pool-watcher:
149+
enabled: true
150+
refresh-interval: 30
151+
```
152+
153+
### Status Watcher Settings
154+
155+
| Field | Description | Example |
156+
|-----------------------|-------------------------------------------------------------------------|-----------|
157+
| `refresh-interval` | Time, in seconds, between two consecutive collections of status data | `60` |
158+
159+
```yaml
160+
status-watcher:
161+
refresh-interval: 30
162+
```
163+
164+
### Network Watcher Settings
165+
166+
| Field | Description | Example |
167+
|-----------------------|-------------------------------------------------------------------------|-----------|
168+
| `enabled` | Enable network watcher | `True` |
169+
| `refresh-interval` | Time, in seconds, between two consecutive collections of network data | `60` |
170+
171+
```yaml
172+
network-watcher:
173+
enabled: true
174+
refresh-interval: 30
175+
```
176+
177+
### Database Settings
178+
179+
| Field | Description | Example |
180+
|------------|----------------------------------------------|----------------|
181+
| `path` | Path to the database file | `"watcher.db"` |
182+
183+
```yaml
184+
database:
185+
path: "watcher.db"
186+
```
187+
188+
### Blockfrost Settings
189+
190+
| Field | Description | Example |
191+
|---------------|-----------------------------------------------------------------------------|---------------------------------------------------------|
192+
| `project-id` | Blockfrost project ID | `"thisissecret"` |
193+
| `endpoint` | Blockfrost API endpoint | `"https://cardano-mainnet.blockfrost.io/api/v0"` |
194+
| `max-routines`| Number of routines used by Blockfrost to perform concurrent actions | `10` |
195+
| `timeout` | Timeout for requests to the Blockfrost API (in seconds) | `60` |
196+
197+
```yaml
198+
blockfrost:
199+
project-id: "thisissecret"
200+
endpoint: "https://cardano-mainnet.blockfrost.io/api/v0"
201+
max-routines: 10
202+
timeout: 60
203+
```
204+
205+
### HTTP Server Settings
206+
207+
| Field | Description | Example |
208+
|------------|--------------------------------------------------|-----------|
209+
| `port` | Port on which the HTTP server should listen | `8080` |
210+
211+
```yaml
212+
http:
213+
host: "0.0.0.0"
214+
port: 8080
215+
```
216+
217+
### Cardano Settings
218+
219+
| Field | Description | Example |
220+
|----------------|--------------------------------------------------------------|---------------------------|
221+
| `config-dir` | Path to the directory where Cardano configuration files are stored | `"config"` |
222+
| `socket-path` | Path of the socket to communicate with a Cardano node | `"/tmp/cardano.socket"` |
223+
| `timezone` | Timezone to use with cardano-cli | `"UTC"` |
224+
225+
```yaml
226+
cardano:
227+
config-dir: "config"
228+
socket-path: "/tmp/cardano.socket"
229+
timezone: "UTC"
230+
```
231+
232+
## Metrics
233+
234+
| Metric Name | Description | Type | Labels |
235+
| ----------------------------------------------------------------- | -------------------- |---- | --- |
236+
| `cardano_validator_watcher_pool_relay_count` | Number of relays associated with each pool | GaugeVec | `pool_name`, `pool_id`, `pool_instance` |
237+
| `cardano_validator_watcher_pool_pledge_met` | Indicates whether the pool has met its pledge requirements or not (0 or 1) | GaugeVec | `pool_name`, `pool_id`, `pool_instance` |
238+
| `cardano_validator_watcher_pool_saturation_level` | The current saturation level of the pool in percent | GaugeVec | `pool_name`, `pool_id`, `pool_instance` |
239+
| `cardano_validator_watcher_next_epoch_start_time` | Start time of the next epoch in seconds | Gauge | - |
240+
| `cardano_validator_watcher_monitored_validators_count` | Number of validators monitored by the watcher | Gauge | - |
241+
| `cardano_validator_watcher_missed_blocks` | Number of missed blocks in the current epoch | CounterVec | `pool_name`, `pool_id`, `pool_instance`, `epoch` |
242+
| `cardano_validator_watcher_consecutive_missed_blocks` | Number of blocks missed consecutively. | GaugeVec | `pool_name`, `pool_id`, `pool_instance`, `epoch` |
243+
| `cardano_validator_watcher_validated_blocks` | Number of validated blocks in the current epoch | CounterVec | `pool_name`, `pool_id`, `pool_instance`, `epoch` |
244+
| `cardano_validator_watcher_orphaned_blocks` | Number of orphaned blocks in the current epoch | CounterVec | `pool_name`, `pool_id`, `pool_instance`, `epoch` |
245+
| `cardano_validator_watcher_expected_blocks` | Number of expected blocks in the current epoch | CounterVec | `pool_name`, `pool_id`, `pool_instance`, `epoch` |
246+
| `cardano_validator_watcher_latest_slot_processed_by_block_watcher`| Latest slot processed by block watcher | Gauge | - |
247+
| `cardano_validator_watcher_next_slot_leader` | Next slot leader for each monitored pool | GaugeVec | `pool_name`, `pool_id`, `pool_instance`, `epoch` |
248+
| `cardano_validator_watcher_epoch_duration` | Duration of an epoch in days | Gauge | - |
249+
| `cardano_validator_watcher_network_epoch` | Current epoch number | Gauge | - |
250+
| `cardano_validator_watcher_network_block_height` | Latest known block height | Gauge | - |
251+
| `cardano_validator_watcher_network_slot` | Latest known slot | Gauge | - |
252+
| `cardano_validator_watcher_network_epoch_slot` | Latest known epoch slot | Gauge | - |
253+
| `cardano_validator_watcher_network_network_pools_total` | Total number of pools in the network | Gauge | - |
254+
| `cardano_validator_watcher_network_blocks_proposed_current_epoch` | Number of blocks proposed in the current epoch by the network | Gauge | - |
255+
| `cardano_validator_watcher_network_active_stake` | Total active stake in the network | Gauge | - |
256+
| `cardano_validator_watcher_chain_id` | ID of the chain | Gauge | - |
257+
| `cardano_validator_watcher_health_status` | Health status of the Cardano validator watcher: 1 = healthy, 0 = unhealthy | Gauge | - |

‎config.example.yaml

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
pools:
2+
- instance: instance_1
3+
id: pool_bench32_id
4+
name: pool_name
5+
key: config/pool_name.vrf.skey
6+
exclude: false
7+
- instance: instance_2
8+
id: pool_bench32_id
9+
name: pool_name
10+
key: config/pool_name.vrf.skey
11+
exclude: true
12+
allow-empty-slots: true
13+
network: mainnet
14+
block-watcher:
15+
enabled: true
16+
refresh-interval: 60
17+
pool-watcher:
18+
enabled: true
19+
refresh-interval: 60
20+
network-watcher:
21+
enabled: true
22+
refresh-interval: 60
23+
status-watcher:
24+
refresh-interval: 15
25+
database:
26+
path: watcher.db
27+
blockfrost:
28+
project-id: "thisissecret"
29+
endpoint: https://cardano-mainnet.blockfrost.io/api/v0
30+
max-routines: 10
31+
timeout: 60
32+
http:
33+
host: "0.0.0.0"
34+
port: 8080
35+
cardano:
36+
config-dir: config
37+
socket-path: /tmp/cardano.socket
38+
timezone: UTC

‎docs/images/banner.jpg

77.2 KB
Loading

0 commit comments

Comments
 (0)