1use crate::budget::{AttemptUsage, UsageSnapshot};
11use crate::error::FdbError;
12use crate::transaction::ConflictingKeyRange;
13use std::collections::HashMap;
14use std::sync::{Arc, Mutex};
15use std::time::Duration;
16
17pub type Labels = Vec<(String, String)>;
19
20#[derive(Clone, Hash, Eq, PartialEq, Debug)]
22pub struct MetricKey {
23 pub name: String,
24 pub labels: Labels,
25}
26
27impl MetricKey {
28 pub fn new(name: &str, labels: &[(&str, &str)]) -> Self {
37 let mut sorted_labels: Labels = labels
39 .iter()
40 .map(|(k, v)| (k.to_string(), v.to_string()))
41 .collect();
42
43 sorted_labels.sort_by(|a, b| a.0.cmp(&b.0));
45
46 Self {
47 name: name.to_string(),
48 labels: sorted_labels,
49 }
50 }
51}
52
53#[derive(Debug, Clone)]
58#[non_exhaustive]
59pub enum AttemptOutcome {
60 Committed,
63 Retried { cause: FdbError },
67 Failed,
70}
71
72#[derive(Debug, Clone, Default)]
78pub enum ConflictKeys {
79 #[default]
81 NotRequested,
82 Available(Vec<ConflictingKeyRange>),
85 ReadFailed(FdbError),
87}
88
89impl ConflictKeys {
90 pub fn ranges(&self) -> &[ConflictingKeyRange] {
92 match self {
93 ConflictKeys::Available(ranges) => ranges,
94 ConflictKeys::NotRequested | ConflictKeys::ReadFailed(_) => &[],
95 }
96 }
97}
98
99#[derive(Debug, Clone)]
105pub struct AttemptMetrics {
106 pub index: usize,
108 pub usage: UsageSnapshot,
111 pub custom_metrics: HashMap<MetricKey, u64>,
114 pub duration: Option<Duration>,
117 pub commit_duration: Option<Duration>,
119 pub grv_duration: Option<Duration>,
122 pub on_error_duration: Option<Duration>,
125 pub outcome: AttemptOutcome,
127 pub conflicting_keys: ConflictKeys,
129 pub read_version: Option<i64>,
133}
134
135#[derive(Debug, Default, Clone)]
137pub struct TransactionInfo {
138 pub retries: u64,
141 pub conflict_count: u64,
143 pub read_version: Option<i64>,
145 pub commit_version: Option<i64>,
147}
148
149#[derive(Debug, Clone, Default)]
152pub struct MetricsReport {
153 pub attempts: Vec<AttemptMetrics>,
156 pub total_duration: Option<Duration>,
158 pub transaction: TransactionInfo,
160}
161
162impl MetricsReport {
163 pub fn total_usage(&self) -> UsageSnapshot {
169 self.attempts
170 .iter()
171 .fold(UsageSnapshot::default(), |mut total, attempt| {
172 let usage = &attempt.usage;
173 total.elapsed += usage.elapsed;
174 total.bytes_read += usage.bytes_read;
175 total.bytes_written += usage.bytes_written;
176 total.keys_values_fetched += usage.keys_values_fetched;
177 total.call_get += usage.call_get;
178 total.call_get_range += usage.call_get_range;
179 total.call_set += usage.call_set;
180 total.call_clear += usage.call_clear;
181 total.call_clear_range += usage.call_clear_range;
182 total.call_atomic_op += usage.call_atomic_op;
183 total
184 })
185 }
186
187 pub fn last_attempt(&self) -> Option<&AttemptMetrics> {
189 self.attempts.last()
190 }
191}
192
193#[derive(Debug, Default)]
200struct OpenAttempt {
201 usage: Option<Arc<AttemptUsage>>,
202 duration: Option<Duration>,
203 commit_duration: Option<Duration>,
204 grv_duration: Option<Duration>,
205 conflicting_keys: ConflictKeys,
206 read_version: Option<i64>,
207}
208
209#[derive(Debug, Clone, Default)]
216pub struct TransactionMetrics {
217 pub metrics: Arc<Mutex<MetricsReport>>,
219 open: Arc<Mutex<OpenAttempt>>,
221}
222
223impl TransactionMetrics {
224 pub fn new() -> Self {
226 Self::default()
227 }
228
229 fn report(&self) -> std::sync::MutexGuard<'_, MetricsReport> {
230 self.metrics
231 .lock()
232 .unwrap_or_else(|poisoned| poisoned.into_inner())
233 }
234
235 fn open(&self) -> std::sync::MutexGuard<'_, OpenAttempt> {
236 self.open
237 .lock()
238 .unwrap_or_else(|poisoned| poisoned.into_inner())
239 }
240
241 pub(crate) fn begin_attempt(&self, usage: Arc<AttemptUsage>) {
250 let mut open = self.open();
251
252 #[cfg(feature = "trace")]
253 if let Some(dropped) = open.usage.as_ref() {
254 let snapshot = dropped.snapshot();
260 let idle = snapshot
261 == UsageSnapshot {
262 elapsed: snapshot.elapsed,
263 ..UsageSnapshot::default()
264 }
265 && dropped.custom_metrics().is_empty()
266 && open.read_version.is_none()
267 && open.duration.is_none()
268 && open.commit_duration.is_none()
269 && open.grv_duration.is_none()
270 && matches!(open.conflicting_keys, ConflictKeys::NotRequested);
271
272 if !idle {
273 tracing::warn!(
274 "a new attempt was opened while the previous one was still open, its usage and custom metrics are dropped (set_client_budget or reset called mid-attempt)"
275 );
276 }
277 }
278
279 *open = OpenAttempt {
280 usage: Some(usage),
281 ..OpenAttempt::default()
282 };
283 }
284
285 pub(crate) fn mark_attempt_end(&self) {
289 let mut open = self.open();
290 if open.duration.is_none() {
291 open.duration = open.usage.as_ref().map(|usage| usage.elapsed());
292 }
293 }
294
295 pub(crate) fn record_commit(&self, duration: Duration) {
298 let mut open = self.open();
299 open.commit_duration = Some(duration);
300 if open.duration.is_none() {
301 open.duration = open.usage.as_ref().map(|usage| usage.elapsed());
302 }
303 }
304
305 pub(crate) fn record_grv(
308 &self,
309 usage: &Arc<AttemptUsage>,
310 duration: Duration,
311 version: Option<i64>,
312 ) {
313 let mut open = self.open();
314 if !open
315 .usage
316 .as_ref()
317 .is_some_and(|current| Arc::ptr_eq(current, usage))
318 {
319 return;
320 }
321 if open.grv_duration.is_none() {
322 open.grv_duration = Some(duration);
323 }
324 if let Some(version) = version {
325 open.read_version = Some(version);
326 self.report().transaction.read_version = Some(version);
327 }
328 }
329
330 pub fn finish_attempt(&self, outcome: AttemptOutcome) {
335 let (usage, open) = {
336 let mut open = self.open();
337 match open.usage.take() {
338 Some(usage) => (usage, std::mem::take(&mut *open)),
340 None => return,
341 }
342 };
343
344 let retried = matches!(outcome, AttemptOutcome::Retried { .. });
345
346 let mut report = self.report();
347 let index = report.attempts.len();
348 report.attempts.push(AttemptMetrics {
349 index,
350 usage: usage.snapshot(),
351 custom_metrics: usage.custom_metrics(),
352 duration: open.duration.or_else(|| Some(usage.elapsed())),
353 commit_duration: open.commit_duration,
354 grv_duration: open.grv_duration,
355 on_error_duration: None,
356 outcome,
357 conflicting_keys: open.conflicting_keys,
358 read_version: open.read_version,
359 });
360
361 if retried {
362 report.transaction.retries += 1;
363 }
364 }
365
366 pub fn set_on_error_duration(&self, duration: Duration) {
371 if let Some(attempt) = self.report().attempts.last_mut() {
372 attempt.on_error_duration = Some(duration);
373 }
374 }
375
376 pub fn set_total_duration(&self, duration: Duration) {
378 self.report().total_duration = Some(duration);
379 }
380
381 pub fn set_read_version(&self, version: i64) {
383 self.open().read_version = Some(version);
384 self.report().transaction.read_version = Some(version);
385 }
386
387 pub fn set_commit_version(&self, version: i64) {
389 self.report().transaction.commit_version = Some(version);
390 }
391
392 pub fn set_conflicting_keys(&self, keys: ConflictKeys) {
394 self.open().conflicting_keys = keys;
395 }
396
397 pub fn increment_conflict_count(&self) {
399 self.report().transaction.conflict_count += 1;
400 }
401
402 pub fn get_retries(&self) -> u64 {
404 self.report().transaction.retries
405 }
406
407 pub fn get_metrics_data(&self) -> MetricsReport {
409 self.report().clone()
410 }
411
412 pub fn get_transaction_info(&self) -> TransactionInfo {
414 self.report().transaction.clone()
415 }
416}
417
418#[cfg(test)]
419mod tests {
420 use super::*;
421 use std::collections::HashSet;
422
423 #[test]
424 fn test_metric_key_equality() {
425 let key1 = MetricKey::new("counter", &[("region", "us-west"), ("service", "api")]);
427 let key2 = MetricKey::new("counter", &[("service", "api"), ("region", "us-west")]);
428
429 assert_eq!(key1, key2);
431
432 let key3 = MetricKey::new("counter", &[("region", "us-east"), ("service", "api")]);
434 assert_ne!(key1, key3);
435
436 let key4 = MetricKey::new("counter", &[("zone", "us-west"), ("service", "api")]);
438 assert_ne!(key1, key4);
439
440 let key5 = MetricKey::new("timer", &[("region", "us-west"), ("service", "api")]);
442 assert_ne!(key1, key5);
443 }
444
445 #[test]
446 fn test_metric_key_in_hashmap() {
447 let mut metrics = HashMap::new();
448
449 metrics.insert(
451 MetricKey::new("counter", &[("region", "us-west"), ("service", "api")]),
452 100,
453 );
454 metrics.insert(
455 MetricKey::new("counter", &[("region", "us-east"), ("service", "api")]),
456 200,
457 );
458 metrics.insert(
459 MetricKey::new("timer", &[("region", "us-west"), ("service", "api")]),
460 300,
461 );
462
463 assert_eq!(
465 metrics.get(&MetricKey::new(
466 "counter",
467 &[("region", "us-west"), ("service", "api")]
468 )),
469 Some(&100)
470 );
471
472 assert_eq!(
474 metrics.get(&MetricKey::new(
475 "counter",
476 &[("service", "api"), ("region", "us-west")]
477 )),
478 Some(&100)
479 );
480
481 assert_eq!(
483 metrics.get(&MetricKey::new(
484 "counter",
485 &[("region", "us-east"), ("service", "api")]
486 )),
487 Some(&200)
488 );
489
490 assert_eq!(
492 metrics.get(&MetricKey::new(
493 "timer",
494 &[("region", "us-west"), ("service", "api")]
495 )),
496 Some(&300)
497 );
498 }
499
500 #[test]
501 fn test_metric_key_label_order_independence() {
502 let mut unique_keys = HashSet::new();
504
505 unique_keys.insert(MetricKey::new(
507 "counter",
508 &[("a", "1"), ("b", "2"), ("c", "3")],
509 ));
510 unique_keys.insert(MetricKey::new(
511 "counter",
512 &[("a", "1"), ("c", "3"), ("b", "2")],
513 ));
514 unique_keys.insert(MetricKey::new(
515 "counter",
516 &[("b", "2"), ("a", "1"), ("c", "3")],
517 ));
518 unique_keys.insert(MetricKey::new(
519 "counter",
520 &[("b", "2"), ("c", "3"), ("a", "1")],
521 ));
522 unique_keys.insert(MetricKey::new(
523 "counter",
524 &[("c", "3"), ("a", "1"), ("b", "2")],
525 ));
526 unique_keys.insert(MetricKey::new(
527 "counter",
528 &[("c", "3"), ("b", "2"), ("a", "1")],
529 ));
530
531 assert_eq!(unique_keys.len(), 1);
533 }
534
535 #[test]
538 fn attempts_are_recorded_one_by_one() {
539 let metrics = TransactionMetrics::new();
540 let key = MetricKey::new("documents", &[]);
541
542 metrics.finish_attempt(AttemptOutcome::Failed);
544 assert!(metrics.get_metrics_data().attempts.is_empty());
545
546 let first = Arc::new(AttemptUsage::new());
547 metrics.begin_attempt(first.clone());
548 first.record_set(10);
549 first.increment_custom(key.clone(), 1);
550 metrics.record_commit(Duration::from_millis(3));
551 metrics.record_grv(&first, Duration::from_millis(5), None);
552 metrics.record_grv(&first, Duration::from_millis(1), Some(42)); metrics.finish_attempt(AttemptOutcome::Retried {
554 cause: FdbError::from_code(1020),
555 });
556 metrics.set_on_error_duration(Duration::from_millis(7));
557
558 let second = Arc::new(AttemptUsage::new());
559 metrics.begin_attempt(second.clone());
560 metrics.record_grv(&first, Duration::from_millis(20), None);
561 second.record_set(4);
562 second.increment_custom(key.clone(), 2);
563 metrics.finish_attempt(AttemptOutcome::Committed);
564
565 metrics.finish_attempt(AttemptOutcome::Failed);
567
568 let report = metrics.get_metrics_data();
569 assert_eq!(report.attempts.len(), 2);
570 assert_eq!(report.transaction.retries, 1);
571 assert_eq!(report.transaction.read_version, Some(42));
572
573 let first = &report.attempts[0];
574 assert_eq!(first.index, 0);
575 assert_eq!(first.usage.bytes_written, 10);
576 assert_eq!(first.custom_metrics.get(&key), Some(&1));
577 assert_eq!(first.commit_duration, Some(Duration::from_millis(3)));
578 assert_eq!(first.grv_duration, Some(Duration::from_millis(5)));
579 assert_eq!(first.on_error_duration, Some(Duration::from_millis(7)));
580 assert!(matches!(
581 first.outcome,
582 AttemptOutcome::Retried { cause } if cause.code() == 1020
583 ));
584
585 let second = &report.attempts[1];
586 assert_eq!(second.index, 1);
587 assert_eq!(second.usage.bytes_written, 4);
588 assert_eq!(second.custom_metrics.get(&key), Some(&2));
589 assert!(second.commit_duration.is_none());
590 assert!(second.grv_duration.is_none());
591 assert!(second.read_version.is_none());
592 assert!(matches!(second.outcome, AttemptOutcome::Committed));
593
594 assert_eq!(report.total_usage().bytes_written, 14);
595 assert_eq!(report.total_usage().call_set, 2);
596 }
597
598 #[test]
608 fn dropped_attempt_with_only_read_version_is_handled() {
609 let metrics = TransactionMetrics::new();
610
611 let first = Arc::new(AttemptUsage::new());
612 metrics.begin_attempt(first.clone());
613 metrics.set_read_version(42);
614
615 let second = Arc::new(AttemptUsage::new());
619 metrics.begin_attempt(second.clone());
620 second.record_set(1);
621 metrics.finish_attempt(AttemptOutcome::Committed);
622
623 let report = metrics.get_metrics_data();
624 assert_eq!(report.attempts.len(), 1);
625 let only = &report.attempts[0];
626 assert_eq!(only.usage.bytes_written, 1);
627 assert!(matches!(only.outcome, AttemptOutcome::Committed));
628
629 assert_eq!(report.transaction.read_version, Some(42));
632 }
633}