Skip to content

Commit

Permalink
Fees alert (#30)
Browse files Browse the repository at this point in the history 
* Refactored doc, moved to each metric file
  • Loading branch information
@feliam
feliam authored Feb 18, 2025
1 parent cd89468 commit 100ba57
Show file tree
Hide file tree
Showing 14 changed files with 124 additions and 331 deletions.
3 changes: 0 additions & 3 deletions .env.example
View file

This file was deleted.

17 changes: 7 additions & 10 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,16 @@ Namada Monitoring is a tool designed to track and report various metrics related
## Features

- **Block Height Counter**: Tracks the latest block height of the Namada blockchain.
- **Block Time**: Tracks the time spent processing a block.
- **Bonding Activity Metrics**: Measures the total amount of tokens bonded and unbonded per epoch.
- **Epoch Counter**: Tracks the latest epoch recorded on the blockchain.
- **Fees tracker**: Total fees paid per block and per token.
- **Peer Count**: Tracks the number of active peers known to the node.
- **Total Supply of Native Token**: Monitors the total supply of Namada's native token.
- **Transaction Metrics**: Tracks transaction activity, including batch sizes and transaction types per epoch.
- **Transfers amounts**: Tracks the total transfer amount per token and epoch.
- **Voting Power Metrics**: Tracks the number of validators required to reach 1/3 and 2/3 of the total voting power.
- **Peer Count**: Tracks the number of active peers known to the node.
- **Fees count**: Tracks the total fees paid per block and per token.


## Prerequisites

Expand Down Expand Up @@ -48,15 +51,9 @@ cargo run -- --rpc <vector of rpc urls>

1. **Build docker image**
```sh
docker build -t namada-monitoring .
docker build -t namada/monitoring .
```
2. **Run docker image**
```sh
docker run -it -p 9184:9184 --rm eca6f5e0be68 --rpc https://rpc.namada-archive.citizenweb3.com
docker run -it -p 9184:9184 --rm namada/monitoring --rpc https://rpc.namada-archive.citizenweb3.com
```

## Run in a docker compose with prometheus
```sh
docker compose up -d
```
Then check prometheus ui here: http://localhost:9184
23 changes: 0 additions & 23 deletions docker-compose.yml
View file

This file was deleted.

83 changes: 0 additions & 83 deletions namada-alerts.yml
View file

This file was deleted.

10 changes: 0 additions & 10 deletions prometheus.yml
View file

This file was deleted.

197 changes: 11 additions & 186 deletions src/metrics/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,198 +3,23 @@
| **Metric Name** | **Description** |
|---------------------------------|------------------------------------------------------|
| `namada_block_height` | Tracks the latest block height of the Namada blockchain. |
| `epoch` | Tracks the latest epoch recorded on the blockchain. |
| `total_supply_native_token` | Monitors the total supply of Namada's native token. |
| `block_time` | Tracks the time spent processing a block. |
| `bonds_per_epoch` | Measures the total amount of tokens bonded per epoch. |
| `unbonds_per_epoch` | Measures the total amount of tokens unbonded per epoch. |
| `epoch` | Tracks the latest epoch recorded on the blockchain. |
| `fees` | Total fees paid per block and per token |
| `peers` | Number of active peers known to the node, labeled by moniker |
| `total_supply_native_token` | Monitors the total supply of Namada's native token. |
| `transaction_batch_size` | Tracks the distribution of transactions within a batch. |
| `transaction_kind` | Counts the number of transactions by type per epoch. |
| `transfer_amount` | Tracks the total transfer amount per token and epoch. |
| `one_third_threshold` | The number of validators needed to reach 1/3 voting power. |
| `two_third_threshold` | The number of validators needed to reach 2/3 voting power. |
| `peers` | Number of active peers known to the node, labeled by moniker |
| `fees` | Total fees paid per block and per token |

## Block Height Counter (namada_block_height)

This metric tracks the latest block height of the Namada blockchain. It provides a real-time view of block progression, and helps monitor chain liveness and ensure continuous block production.

* The metric is a monotonic counter that increments as new blocks are added to the chain.
* It is updated at each block by fetching the latest block height from the blockchain state.

### Example
```
# HELP namada_block_height the latest block height recorded
# TYPE namada_block_height counter
namada_block_height{chain_id="$CHAINID"} 12960
```


## Bonding Activity Metrics (bonds_per_epoch, unbonds_per_epoch)

These metrics track the number of bonds and unbonds per epoch in the Namada blockchains. They help monitor staking activity, validator participation, and network security dynamics. These metrics are gauges, updated at the start of each epoch based on the blockchain state.


* bonds_per_epoch: Measures the total amount of tokens bonded in a given epoch.
* unbonds_per_epoch: Measures the total amount of tokens unbonded in a given epoch.


### Example
```
# HELP namada_bonds_per_epoch Total bonds per epoch
# TYPE namada_bonds_per_epoch gauge
namada_bonds_per_epoch{epoch="2160",chain_id="local.300e84e1e16080e34547d538"} 120000000000
# HELP namada_unbonds_per_epoch Total unbonds per epoch
# TYPE namada_unbonds_per_epoch gauge
namada_unbonds_per_epoch{epoch="2160",chain_id="local.300e84e1e16080e34547d538"} 0
```


## Epoch Counter (epoch)

This metric tracks the latest epoch recorded on the Namada blockchain, providing visibility into epoch progression and chain activity over time.

### Usage and Interpretation
• A steadily increasing counter indicates normal epoch progression.
• Stagnation or irregular jumps may signal network disruptions, delayed finalization, or protocol changes.
• Analysts can use this metric to detect anomalies in epoch transitions and ensure expected blockchain activity.

* epoch: A monotonic counter that increments as new epochs are finalized.

### Example
```
# HELP epoch The latest epoch recorded
# TYPE epoch counter
epoch 256
```

## Total Supply of Native Token (total_supply_native_token)

This metric tracks the total supply of the native token on the Namada blockchain. Namada blockchain mints NAM tokens as rewards for validators and delegators who secure the network through Cubic Proof-of-Stake. Users also earn NAM tokens for shielding assets and contributing to shared data protection14. The total supply of NAM tokens will be 1 billion

### Usage and Interpretation
• An increasing supply may indicate token minting due to staking rewards or protocol inflation.
• A stable or decreasing supply could suggest burning mechanisms, slashing events, or governance changes.
• Monitoring this metric helps track the economic policies of the blockchain.

* total_supply_native_token: A monotonic counter that records the latest total supply of the native token.


### Example
```
# HELP total_supply_native_token The latest total supply of the native token recorded
# TYPE total_supply_native_token counter
total_supply_native_token 1000000000
```


## Transaction Metrics

This set of metrics tracks transaction activity in the Namada blockchain, capturing both batch sizes and transaction kinds per epoch. These metrics help monitor network load, transaction diversity, and failure rates.

### transaction_batch_size (Histogram)

Measures the number of inner transactions within a batch. Provides insights into how transactions are grouped and processed. Uses predefined buckets (1, 2, 4, 8, ..., 256)

#### Usage and Interpretation
• A skewed distribution in transaction_batch_size may suggest inefficient batch processing.

### Example
```
# HELP transaction_batch_size The number of inner transactions in the batch
# TYPE transaction_batch_size histogram
transaction_batch_size_bucket{le="1"} 5
transaction_batch_size_bucket{le="2"} 10
transaction_batch_size_bucket{le="4"} 20
transaction_batch_size_bucket{le="8"} 30
transaction_batch_size_bucket{le="16"} 40
transaction_batch_size_bucket{le="32"} 50
transaction_batch_size_bucket{le="64"} 60
transaction_batch_size_bucket{le="128"} 70
transaction_batch_size_bucket{le="256"} 80
transaction_batch_size_count 80
transaction_batch_size_sum 3200
```

### transaction_kind (CounterVec)

Tracks the count of different transaction types per epoch.

#### Labels:
- kind: The specific type of transaction:
- transfer: Standard token transfer.
- ibc_transfer: Cross-chain transfer via IBC.
- bond/unbond/redelegate: Staking-related actions.
- claim_rewards/withdraw: Reward and withdrawal operations.
- vote_proposal/init_proposal: Governance voting and proposal creation.
- metadata_change/commission_change”: Validator updates.
- reveal_public_key: Public key revelation.
- become_validator/deactivate_validator/reactivate_validator/unjail_validator: Validator lifecycle actions.
- epoch: The epoch in which the transaction was included.
- failed: A boolean (true/false) indicating if the transaction failed.

### Usage and Interpretation
• A steady count in transaction_kind indicates normal blockchain activity.
• A high failure rate (failed = "true") should be considered abnormal.

### Example
```
# HELP transaction_kind Transaction kind count per epoch
# TYPE transaction_kind counter
transaction_kind{kind="transfer", epoch="256", failed="false"} 120
transaction_kind{kind="bond", epoch="256", failed="false"} 15
transaction_kind{kind="vote_proposal", epoch="256", failed="true"} 3
```

## Voting Power Metrics (one_third_threshold, two_third_threshold)

These metrics track the number of validators required to reach 1/3 and 2/3 of the total voting power. They provide insight into consensus formation and validator distribution in the Namada blockchain.

### Labels:
- one_third_threshold: The number of validators needed to reach 1/3 of the voting power.
- two_third_threshold: The number of validators needed to reach 2/3 of the voting power.

### Usage and Interpretation
- If the `one_third_threshold` is low, a small number of validators hold significant influence, potentially increasing centralization risks.
- If the `two_third_threshold` is low, it may indicate that a small group can finalize blocks quickly, but also raises concerns about validator distribution.
- These metrics help assess network decentralization and validator power concentration.

### Example
```
# HELP one_third_threshold Number of validators to reach 1/3 of the voting power
# TYPE one_third_threshold gauge
one_third_threshold 5
# HELP two_third_threshold Number of validators to reach 2/3 of the voting power
# TYPE two_third_threshold gauge
two_third_threshold 12
```

## Peer Count (namada_peers)

This metric tracks the number of active peers known to the node. It helps monitor network connectivity, ensuring the node is maintaining a healthy number of connections to other peers. Eg. a bunch of nodes going offline at once - could be a sign of some sort of DoS attack

* The metric is a gauge, meaning it can increase or decrease based on peer availability.
* Each peer is labeled with its moniker

### Example
```
# HELP namada_peers Number of peers known
# TYPE namada_peers gauge
namada_peers{moniker="technodrome-v1.0.0",chain_id="namada.5f5de2dd1b88cba30586420"} 73
namada_peers{moniker="technodrome-v1.0.0-dirty",chain_id="namada.5f5de2dd1b88cba30586420"} 3
namada_peers{moniker="technodrome-v1.0.1-sec.2",chain_id="namada.5f5de2dd1b88cba30586420"} 21
```

## Fees per block (fees)
This metric tracks the total transaction fees paid per block and per token. It helps monitor the gas costs of transactions on the network, providing insight into network congestion and transaction fee trends.
• The metric is a counter, meaning it only increases over time.
• Fees are labeled by the block height and the token used for gas payments.

### Example
```
# HELP namada_fees_counter Total fees paid per block and per token
# TYPE namada_fees_counter counter
namada_fees_counter{height="777604",token="tnam1q9gr66cvu4hrzm0sd5kmlnjje82gs3xlfg3v6nu7",chain_id="housefire-alpaca.cc0d3e0c033be"} 0.5845009999999999
namada_fees_counter{height="777605",token="tnam1q9gr66cvu4hrzm0sd5kmlnjje82gs3xlfg3v6nu7",chain_id="housefire-alpaca.cc0d3e0c033be"} 0.154409
```
## How to add a new metric

1. Add a new metric file to src/metrics/, declare a struct with your metric and implement MetricTRait & Default trait.
2. Consider adding your metric to the default metric set at src/metrcs/mod.rs::MetricsExporter.default_metrics()
3. Update Readme.md to contain your new metric
4. Go use your new metric in an alert or dashboard
Loading

0 comments on commit 100ba57

Please sign in to comment.