kona_engine/metrics/
mod.rs

1//! Prometheus metrics collection for engine operations.
2//!
3//! Provides metric identifiers and labels for monitoring engine performance,
4//! task execution, and block progression through safety levels.
5
6/// Metrics container with constants for Prometheus metric collection.
7///
8/// Contains identifiers for gauges, counters, and histograms used to monitor
9/// engine operations when the `metrics` feature is enabled. Metrics track:
10///
11/// - Block progression through safety levels (unsafe → finalized)
12/// - Task execution success/failure rates by type
13/// - Engine API method call latencies
14///
15/// # Usage
16///
17/// ```rust,ignore
18/// use metrics::{counter, gauge, histogram};
19/// use kona_engine::Metrics;
20///
21/// // Track successful task execution
22/// counter!(Metrics::ENGINE_TASK_SUCCESS, "task" => Metrics::INSERT_TASK_LABEL);
23///
24/// // Record block height at safety level
25/// gauge!(Metrics::BLOCK_LABELS, block_num as f64, "level" => Metrics::SAFE_BLOCK_LABEL);
26///
27/// // Time Engine API calls
28/// histogram!(Metrics::ENGINE_METHOD_REQUEST_DURATION, duration.as_secs_f64());
29/// ```
30#[derive(Debug, Clone)]
31pub struct Metrics;
32
33impl Metrics {
34    /// Identifier for the gauge that tracks block labels.
35    pub const BLOCK_LABELS: &str = "kona_node_block_labels";
36    /// Unsafe block label.
37    pub const UNSAFE_BLOCK_LABEL: &str = "unsafe";
38    /// Cross-unsafe block label.
39    pub const CROSS_UNSAFE_BLOCK_LABEL: &str = "cross-unsafe";
40    /// Local-safe block label.
41    pub const LOCAL_SAFE_BLOCK_LABEL: &str = "local-safe";
42    /// Safe block label.
43    pub const SAFE_BLOCK_LABEL: &str = "safe";
44    /// Finalized block label.
45    pub const FINALIZED_BLOCK_LABEL: &str = "finalized";
46
47    /// Identifier for the counter that records engine task counts.
48    pub const ENGINE_TASK_SUCCESS: &str = "kona_node_engine_task_count";
49    /// Identifier for the counter that records engine task counts.
50    pub const ENGINE_TASK_FAILURE: &str = "kona_node_engine_task_failure";
51
52    /// Insert task label.
53    pub const INSERT_TASK_LABEL: &str = "insert";
54    /// Consolidate task label.
55    pub const CONSOLIDATE_TASK_LABEL: &str = "consolidate";
56    /// Forkchoice task label.
57    pub const FORKCHOICE_TASK_LABEL: &str = "forkchoice-update";
58    /// Build task label.
59    pub const BUILD_TASK_LABEL: &str = "build";
60    /// Finalize task label.
61    pub const FINALIZE_TASK_LABEL: &str = "finalize";
62
63    /// Identifier for the histogram that tracks engine method call time.
64    pub const ENGINE_METHOD_REQUEST_DURATION: &str = "kona_node_engine_method_request_duration";
65    /// `engine_forkchoiceUpdatedV<N>` label
66    pub const FORKCHOICE_UPDATE_METHOD: &str = "engine_forkchoiceUpdated";
67    /// `engine_newPayloadV<N>` label.
68    pub const NEW_PAYLOAD_METHOD: &str = "engine_newPayload";
69    /// `engine_getPayloadV<N>` label.
70    pub const GET_PAYLOAD_METHOD: &str = "engine_getPayload";
71
72    /// Identifier for the counter that tracks the number of times the engine has been reset.
73    pub const ENGINE_RESET_COUNT: &str = "kona_node_engine_reset_count";
74
75    /// Initializes metrics for the engine.
76    ///
77    /// This does two things:
78    /// * Describes various metrics.
79    /// * Initializes metrics to 0 so they can be queried immediately.
80    #[cfg(feature = "metrics")]
81    pub fn init() {
82        Self::describe();
83        Self::zero();
84    }
85
86    /// Describes metrics used in [`kona_engine`][crate].
87    #[cfg(feature = "metrics")]
88    pub fn describe() {
89        // Block labels
90        metrics::describe_gauge!(Self::BLOCK_LABELS, "Blockchain head labels");
91
92        // Engine task counts
93        metrics::describe_counter!(Self::ENGINE_TASK_SUCCESS, "Engine tasks successfully executed");
94        metrics::describe_counter!(Self::ENGINE_TASK_FAILURE, "Engine tasks failed");
95
96        // Engine method request duration histogram
97        metrics::describe_histogram!(
98            Self::ENGINE_METHOD_REQUEST_DURATION,
99            metrics::Unit::Seconds,
100            "Engine method request duration"
101        );
102
103        // Engine reset counter
104        metrics::describe_counter!(
105            Self::ENGINE_RESET_COUNT,
106            metrics::Unit::Count,
107            "Engine reset count"
108        );
109    }
110
111    /// Initializes metrics to `0` so they can be queried immediately by consumers of prometheus
112    /// metrics.
113    #[cfg(feature = "metrics")]
114    pub fn zero() {
115        // Engine task counts
116        kona_macros::set!(counter, Self::ENGINE_TASK_SUCCESS, Self::INSERT_TASK_LABEL, 0);
117        kona_macros::set!(counter, Self::ENGINE_TASK_SUCCESS, Self::CONSOLIDATE_TASK_LABEL, 0);
118        kona_macros::set!(counter, Self::ENGINE_TASK_SUCCESS, Self::BUILD_TASK_LABEL, 0);
119        kona_macros::set!(counter, Self::ENGINE_TASK_SUCCESS, Self::FINALIZE_TASK_LABEL, 0);
120
121        kona_macros::set!(counter, Self::ENGINE_TASK_FAILURE, Self::INSERT_TASK_LABEL, 0);
122        kona_macros::set!(counter, Self::ENGINE_TASK_FAILURE, Self::CONSOLIDATE_TASK_LABEL, 0);
123        kona_macros::set!(counter, Self::ENGINE_TASK_FAILURE, Self::BUILD_TASK_LABEL, 0);
124        kona_macros::set!(counter, Self::ENGINE_TASK_FAILURE, Self::FINALIZE_TASK_LABEL, 0);
125
126        // Engine reset count
127        kona_macros::set!(counter, Self::ENGINE_RESET_COUNT, 0);
128    }
129}
kona_engine/metrics/mod.rs

kona_engine/metrics/
mod.rs
