reth_db/
metrics.rs

1use crate::Tables;
2use metrics::Histogram;
3use reth_metrics::{metrics::Counter, Metrics};
4use rustc_hash::FxHashMap;
5use std::time::{Duration, Instant};
6use strum::{EnumCount, EnumIter, IntoEnumIterator};
7
8const LARGE_VALUE_THRESHOLD_BYTES: usize = 4096;
9
10/// Caches metric handles for database environment to make sure handles are not re-created
11/// on every operation.
12///
13/// Requires a metric recorder to be registered before creating an instance of this struct.
14/// Otherwise, metric recording will no-op.
15#[derive(Debug)]
16pub(crate) struct DatabaseEnvMetrics {
17    /// Caches `OperationMetrics` handles for each table and operation tuple.
18    operations: FxHashMap<(&'static str, Operation), OperationMetrics>,
19    /// Caches `TransactionMetrics` handles for counters grouped by only transaction mode.
20    /// Updated both at tx open and close.
21    transactions: FxHashMap<TransactionMode, TransactionMetrics>,
22    /// Caches `TransactionOutcomeMetrics` handles for counters grouped by transaction mode and
23    /// outcome. Can only be updated at tx close, as outcome is only known at that point.
24    transaction_outcomes:
25        FxHashMap<(TransactionMode, TransactionOutcome), TransactionOutcomeMetrics>,
26}
27
28impl DatabaseEnvMetrics {
29    pub(crate) fn new() -> Self {
30        // Pre-populate metric handle maps with all possible combinations of labels
31        // to avoid runtime locks on the map when recording metrics.
32        Self {
33            operations: Self::generate_operation_handles(),
34            transactions: Self::generate_transaction_handles(),
35            transaction_outcomes: Self::generate_transaction_outcome_handles(),
36        }
37    }
38
39    /// Generate a map of all possible operation handles for each table and operation tuple.
40    /// Used for tracking all operation metrics.
41    fn generate_operation_handles() -> FxHashMap<(&'static str, Operation), OperationMetrics> {
42        let mut operations = FxHashMap::with_capacity_and_hasher(
43            Tables::COUNT * Operation::COUNT,
44            Default::default(),
45        );
46        for table in Tables::ALL {
47            for operation in Operation::iter() {
48                operations.insert(
49                    (table.name(), operation),
50                    OperationMetrics::new_with_labels(&[
51                        (Labels::Table.as_str(), table.name()),
52                        (Labels::Operation.as_str(), operation.as_str()),
53                    ]),
54                );
55            }
56        }
57        operations
58    }
59
60    /// Generate a map of all possible transaction modes to metric handles.
61    /// Used for tracking a counter of open transactions.
62    fn generate_transaction_handles() -> FxHashMap<TransactionMode, TransactionMetrics> {
63        TransactionMode::iter()
64            .map(|mode| {
65                (
66                    mode,
67                    TransactionMetrics::new_with_labels(&[(
68                        Labels::TransactionMode.as_str(),
69                        mode.as_str(),
70                    )]),
71                )
72            })
73            .collect()
74    }
75
76    /// Generate a map of all possible transaction mode and outcome handles.
77    /// Used for tracking various stats for finished transactions (e.g. commit duration).
78    fn generate_transaction_outcome_handles(
79    ) -> FxHashMap<(TransactionMode, TransactionOutcome), TransactionOutcomeMetrics> {
80        let mut transaction_outcomes = FxHashMap::with_capacity_and_hasher(
81            TransactionMode::COUNT * TransactionOutcome::COUNT,
82            Default::default(),
83        );
84        for mode in TransactionMode::iter() {
85            for outcome in TransactionOutcome::iter() {
86                transaction_outcomes.insert(
87                    (mode, outcome),
88                    TransactionOutcomeMetrics::new_with_labels(&[
89                        (Labels::TransactionMode.as_str(), mode.as_str()),
90                        (Labels::TransactionOutcome.as_str(), outcome.as_str()),
91                    ]),
92                );
93            }
94        }
95        transaction_outcomes
96    }
97
98    /// Record a metric for database operation executed in `f`.
99    /// Panics if a metric recorder is not found for the given table and operation.
100    pub(crate) fn record_operation<R>(
101        &self,
102        table: &'static str,
103        operation: Operation,
104        value_size: Option<usize>,
105        f: impl FnOnce() -> R,
106    ) -> R {
107        if let Some(metrics) = self.operations.get(&(table, operation)) {
108            metrics.record(value_size, f)
109        } else {
110            f()
111        }
112    }
113
114    /// Record metrics for opening a database transaction.
115    pub(crate) fn record_opened_transaction(&self, mode: TransactionMode) {
116        self.transactions
117            .get(&mode)
118            .expect("transaction mode metric handle not found")
119            .record_open();
120    }
121
122    /// Record metrics for closing a database transactions.
123    #[cfg(feature = "mdbx")]
124    pub(crate) fn record_closed_transaction(
125        &self,
126        mode: TransactionMode,
127        outcome: TransactionOutcome,
128        open_duration: Duration,
129        close_duration: Option<Duration>,
130        commit_latency: Option<reth_libmdbx::CommitLatency>,
131    ) {
132        self.transactions
133            .get(&mode)
134            .expect("transaction mode metric handle not found")
135            .record_close();
136
137        self.transaction_outcomes
138            .get(&(mode, outcome))
139            .expect("transaction outcome metric handle not found")
140            .record(open_duration, close_duration, commit_latency);
141    }
142}
143
144/// Transaction mode for the database, either read-only or read-write.
145#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash, EnumCount, EnumIter)]
146pub(crate) enum TransactionMode {
147    /// Read-only transaction mode.
148    ReadOnly,
149    /// Read-write transaction mode.
150    ReadWrite,
151}
152
153impl TransactionMode {
154    /// Returns the transaction mode as a string.
155    pub(crate) const fn as_str(&self) -> &'static str {
156        match self {
157            Self::ReadOnly => "read-only",
158            Self::ReadWrite => "read-write",
159        }
160    }
161
162    /// Returns `true` if the transaction mode is read-only.
163    pub(crate) const fn is_read_only(&self) -> bool {
164        matches!(self, Self::ReadOnly)
165    }
166}
167
168/// Transaction outcome after a database operation - commit, abort, or drop.
169#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash, EnumCount, EnumIter)]
170pub(crate) enum TransactionOutcome {
171    /// Successful commit of the transaction.
172    Commit,
173    /// Aborted transaction.
174    Abort,
175    /// Dropped transaction.
176    Drop,
177}
178
179impl TransactionOutcome {
180    /// Returns the transaction outcome as a string.
181    pub(crate) const fn as_str(&self) -> &'static str {
182        match self {
183            Self::Commit => "commit",
184            Self::Abort => "abort",
185            Self::Drop => "drop",
186        }
187    }
188
189    /// Returns `true` if the transaction outcome is a commit.
190    pub(crate) const fn is_commit(&self) -> bool {
191        matches!(self, Self::Commit)
192    }
193}
194
195/// Types of operations conducted on the database: get, put, delete, and various cursor operations.
196#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash, EnumCount, EnumIter)]
197pub(crate) enum Operation {
198    /// Database get operation.
199    Get,
200    /// Database put upsert operation.
201    PutUpsert,
202    /// Database put append operation.
203    PutAppend,
204    /// Database delete operation.
205    Delete,
206    /// Database cursor upsert operation.
207    CursorUpsert,
208    /// Database cursor insert operation.
209    CursorInsert,
210    /// Database cursor append operation.
211    CursorAppend,
212    /// Database cursor append duplicates operation.
213    CursorAppendDup,
214    /// Database cursor delete current operation.
215    CursorDeleteCurrent,
216    /// Database cursor delete current duplicates operation.
217    CursorDeleteCurrentDuplicates,
218}
219
220impl Operation {
221    /// Returns the operation as a string.
222    pub(crate) const fn as_str(&self) -> &'static str {
223        match self {
224            Self::Get => "get",
225            Self::PutUpsert => "put-upsert",
226            Self::PutAppend => "put-append",
227            Self::Delete => "delete",
228            Self::CursorUpsert => "cursor-upsert",
229            Self::CursorInsert => "cursor-insert",
230            Self::CursorAppend => "cursor-append",
231            Self::CursorAppendDup => "cursor-append-dup",
232            Self::CursorDeleteCurrent => "cursor-delete-current",
233            Self::CursorDeleteCurrentDuplicates => "cursor-delete-current-duplicates",
234        }
235    }
236}
237
238/// Enum defining labels for various aspects used in metrics.
239enum Labels {
240    /// Label representing a table.
241    Table,
242    /// Label representing a transaction mode.
243    TransactionMode,
244    /// Label representing a transaction outcome.
245    TransactionOutcome,
246    /// Label representing a database operation.
247    Operation,
248}
249
250impl Labels {
251    /// Converts each label variant into its corresponding string representation.
252    pub(crate) const fn as_str(&self) -> &'static str {
253        match self {
254            Self::Table => "table",
255            Self::TransactionMode => "mode",
256            Self::TransactionOutcome => "outcome",
257            Self::Operation => "operation",
258        }
259    }
260}
261
262#[derive(Metrics, Clone)]
263#[metrics(scope = "database.transaction")]
264pub(crate) struct TransactionMetrics {
265    /// Total number of opened database transactions (cumulative)
266    opened_total: Counter,
267    /// Total number of closed database transactions (cumulative)
268    closed_total: Counter,
269}
270
271impl TransactionMetrics {
272    pub(crate) fn record_open(&self) {
273        self.opened_total.increment(1);
274    }
275
276    pub(crate) fn record_close(&self) {
277        self.closed_total.increment(1);
278    }
279}
280
281#[derive(Metrics, Clone)]
282#[metrics(scope = "database.transaction")]
283pub(crate) struct TransactionOutcomeMetrics {
284    /// The time a database transaction has been open
285    open_duration_seconds: Histogram,
286    /// The time it took to close a database transaction
287    close_duration_seconds: Histogram,
288    /// The time it took to prepare a transaction commit
289    commit_preparation_duration_seconds: Histogram,
290    /// Duration of GC update during transaction commit by wall clock
291    commit_gc_wallclock_duration_seconds: Histogram,
292    /// The time it took to conduct audit of a transaction commit
293    commit_audit_duration_seconds: Histogram,
294    /// The time it took to write dirty/modified data pages to a filesystem during transaction
295    /// commit
296    commit_write_duration_seconds: Histogram,
297    /// The time it took to sync written data to the disk/storage during transaction commit
298    commit_sync_duration_seconds: Histogram,
299    /// The time it took to release resources during transaction commit
300    commit_ending_duration_seconds: Histogram,
301    /// The total duration of a transaction commit
302    commit_whole_duration_seconds: Histogram,
303    /// User-mode CPU time spent on GC update during transaction commit
304    commit_gc_cputime_duration_seconds: Histogram,
305}
306
307impl TransactionOutcomeMetrics {
308    /// Record transaction closing with the duration it was open and the duration it took to close
309    /// it.
310    #[cfg(feature = "mdbx")]
311    pub(crate) fn record(
312        &self,
313        open_duration: Duration,
314        close_duration: Option<Duration>,
315        commit_latency: Option<reth_libmdbx::CommitLatency>,
316    ) {
317        self.open_duration_seconds.record(open_duration);
318
319        if let Some(close_duration) = close_duration {
320            self.close_duration_seconds.record(close_duration)
321        }
322
323        if let Some(commit_latency) = commit_latency {
324            self.commit_preparation_duration_seconds.record(commit_latency.preparation());
325            self.commit_gc_wallclock_duration_seconds.record(commit_latency.gc_wallclock());
326            self.commit_audit_duration_seconds.record(commit_latency.audit());
327            self.commit_write_duration_seconds.record(commit_latency.write());
328            self.commit_sync_duration_seconds.record(commit_latency.sync());
329            self.commit_ending_duration_seconds.record(commit_latency.ending());
330            self.commit_whole_duration_seconds.record(commit_latency.whole());
331            self.commit_gc_cputime_duration_seconds.record(commit_latency.gc_cputime());
332        }
333    }
334}
335
336#[derive(Metrics, Clone)]
337#[metrics(scope = "database.operation")]
338pub(crate) struct OperationMetrics {
339    /// Total number of database operations made
340    calls_total: Counter,
341    /// The time it took to execute a database operation (`put/upsert/insert/append/append_dup`)
342    /// with value larger than [`LARGE_VALUE_THRESHOLD_BYTES`] bytes.
343    large_value_duration_seconds: Histogram,
344}
345
346impl OperationMetrics {
347    /// Record operation metric.
348    ///
349    /// The duration it took to execute the closure is recorded only if the provided `value_size` is
350    /// larger than [`LARGE_VALUE_THRESHOLD_BYTES`].
351    pub(crate) fn record<R>(&self, value_size: Option<usize>, f: impl FnOnce() -> R) -> R {
352        self.calls_total.increment(1);
353
354        // Record duration only for large values to prevent the performance hit of clock syscall
355        // on small operations
356        if value_size.is_some_and(|size| size > LARGE_VALUE_THRESHOLD_BYTES) {
357            let start = Instant::now();
358            let result = f();
359            self.large_value_duration_seconds.record(start.elapsed());
360            result
361        } else {
362            f()
363        }
364    }
365}
reth_db/metrics.rs

reth_db/
metrics.rs
