feat: add more prometheus metrics for mempool statistics

Miners (and mock-miners) can report how many transactions are (could be)
included in a block and the reason that they stopped building a block.
This information is very helpful to understand whether the block was
full, the miner ran out of time, the miner was preempted, or there were
no transactions available to mine.

Author: obycode

CHANGELOG.md

@@ -10,6 +10,9 @@ and this project adheres to the versioning scheme outlined in the [README.md](RE
 ### Added
 
 - Added a new RPC endpoint `/v3/health` to query the node's health status. The endpoint returns a 200 status code with relevant synchronization information (including the node's current Stacks tip height, the maximum Stacks tip height among its neighbors, and the difference between these two). A user can use the `difference_from_max_peer` value to decide what is a good threshold for them before considering the node out of sync. The endpoint returns a 500 status code if the query cannot retrieve viable data.
+- Improve prometheus metrics to gain more insights into the current state of the mempool
+  - `stacks_node_miner_stop_reason_total`: Counts the number of times the miner stopped mining due to various reasons.
+  - Always report the number of transactions mined in the last attempt, even if there were 0
 
 ## [3.1.0.0.12]
 

stackslib/src/chainstate/nakamoto/miner.rs

@@ -602,6 +602,7 @@ impl NakamotoBlockBuilder {
         }
 
         if builder.txs.is_empty() {
+            set_last_mined_block_transaction_count(0);
             return Err(Error::NoTransactionsToMine);
         }
 

stackslib/src/chainstate/stacks/miner.rs

@@ -54,7 +54,8 @@ use crate::clarity_vm::clarity::{ClarityInstance, Error as clarity_error};
 use crate::core::mempool::*;
 use crate::core::*;
 use crate::monitoring::{
-    set_last_mined_block_transaction_count, set_last_mined_execution_cost_observed,
+    increment_miner_stop_reason, set_last_mined_block_transaction_count,
+    set_last_mined_execution_cost_observed, MinerStopReason,
 };
 use crate::net::relay::Relayer;
 
@@ -2771,6 +2772,7 @@ fn select_and_apply_transactions_from_mempool<B: BlockBuilder>(
                     (*settings.miner_status.lock().expect("FATAL: mutex poisoned")).is_blocked();
                 if blocked {
                     info!("Miner stopping due to preemption");
+                    increment_miner_stop_reason(MinerStopReason::Preempted);
                     return Ok(None);
                 }
 
@@ -2779,6 +2781,7 @@ fn select_and_apply_transactions_from_mempool<B: BlockBuilder>(
 
                 if block_limit_hit == BlockLimitFunction::LIMIT_REACHED {
                     info!("Miner stopping due to limit reached");
+                    increment_miner_stop_reason(MinerStopReason::LimitReached);
                     return Ok(None);
                 }
                 let time_now = get_epoch_time_ms();
@@ -2787,6 +2790,7 @@ fn select_and_apply_transactions_from_mempool<B: BlockBuilder>(
                         "Miner stopping due to mining time exceeded ({} ms)",
                         max_miner_time_ms
                     );
+                    increment_miner_stop_reason(MinerStopReason::DeadlineReached);
                     return Ok(None);
                 }
                 if let Some(time_estimate) = txinfo.metadata.time_estimate_ms {
@@ -2896,6 +2900,7 @@ fn select_and_apply_transactions_from_mempool<B: BlockBuilder>(
                                 {
                                     info!("Miner stopping due to limit reached");
                                     block_limit_hit = BlockLimitFunction::LIMIT_REACHED;
+                                    increment_miner_stop_reason(MinerStopReason::LimitReached);
                                     return Ok(None);
                                 }
                             }

stackslib/src/core/mempool.rs

@@ -1722,6 +1722,9 @@ impl MemPoolDB {
                                                 !start_with_no_estimate,
                                             ),
                                             None => {
+                                                monitoring::increment_miner_stop_reason(
+                                                    monitoring::MinerStopReason::NoTransactions,
+                                                );
                                                 break MempoolIterationStopReason::NoMoreCandidates;
                                             }
                                         }
@@ -1738,6 +1741,9 @@ impl MemPoolDB {
                                 (tx, update_estimate)
                             }
                             None => {
+                                monitoring::increment_miner_stop_reason(
+                                    monitoring::MinerStopReason::NoTransactions,
+                                );
                                 break MempoolIterationStopReason::NoMoreCandidates;
                             }
                         }

stackslib/src/monitoring/mod.rs

@@ -462,6 +462,33 @@ pub fn get_burnchain_signer() -> Option<BurnchainSigner> {
     None
 }
 
+pub enum MinerStopReason {
+    NoTransactions,
+    Preempted,
+    LimitReached,
+    DeadlineReached,
+}
+
+impl MinerStopReason {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            MinerStopReason::NoTransactions => "no_transactions",
+            MinerStopReason::Preempted => "preempted",
+            MinerStopReason::LimitReached => "limit_reached",
+            MinerStopReason::DeadlineReached => "deadline_reached",
+        }
+    }
+}
+
+// Increment the counter for the given miner stop reason.
+#[allow(unused_variables)]
+pub fn increment_miner_stop_reason(reason: MinerStopReason) {
+    #[cfg(feature = "monitoring_prom")]
+    prometheus::MINER_STOP_REASON_TOTAL
+        .with_label_values(&[reason.as_str()])
+        .inc();
+}
+
 #[derive(Debug)]
 pub struct SetGlobalBurnchainSignerError;
 

stackslib/src/monitoring/prometheus.rs

@@ -254,6 +254,12 @@ lazy_static! {
         "stacks_node_miner_current_median_commitment_low",
         "Low 64 bits of a miner's median commitment over the mining commitment window."
     )).unwrap();
+
+    pub static ref MINER_STOP_REASON_TOTAL: IntCounterVec = register_int_counter_vec!(
+        "stacks_node_miner_stop_reason_total",
+        "Total number of times the miner stopped for each reason",
+        &["reason"]
+    ).unwrap();
 }
 
 pub fn new_rpc_call_timer(path: &str) -> HistogramTimer {